Merge pull request #305 from signalwire/Devon/python-sdk-update

Doc updates to sync with Python SDK

Author: Devon-White

fern/products/server-sdks/pages/reference/python/agents/agent-base/index.mdx

@@ -57,6 +57,7 @@ max-toc-depth: 3
 [registersipusername]: /docs/server-sdks/reference/python/agents/agent-base/register-sip-username
 [registerswaigfunction]: /docs/server-sdks/reference/python/agents/agent-base/register-swaig-function
 [removeskill]: /docs/server-sdks/reference/python/agents/agent-base/remove-skill
+[resetcontexts]: /docs/server-sdks/reference/python/agents/agent-base/reset-contexts
 [run]: /docs/server-sdks/reference/python/agents/agent-base/run
 [serve]: /docs/server-sdks/reference/python/agents/agent-base/serve
 [serverless]: /docs/server-sdks/reference/python/agents/agent-base/serverless
@@ -526,6 +527,9 @@ agent.run()
   <Card title="remove_skill" href="/docs/server-sdks/reference/python/agents/agent-base/remove-skill">
     Unload a skill from the agent.
   </Card>
+  <Card title="reset_contexts" href="/docs/server-sdks/reference/python/agents/agent-base/reset-contexts">
+    Remove all contexts from the agent, returning it to a no-contexts state.
+  </Card>
   <Card title="run" href="/docs/server-sdks/reference/python/agents/agent-base/run">
     Smart entry point that auto-detects the runtime environment and starts the agent accordingly.
   </Card>

fern/products/server-sdks/pages/reference/python/agents/agent-base/reset-contexts.mdx

@@ -0,0 +1,40 @@
+---
+title: "reset_contexts"
+slug: /reference/python/agents/agent-base/reset-contexts
+description: Remove all contexts from the agent, returning it to a no-contexts state.
+max-toc-depth: 3
+---
+
+[ref-agentbase]: /docs/server-sdks/reference/python/agents/agent-base
+[contextbuilderreset]: /docs/server-sdks/reference/python/agents/context-builder/reset
+[setdynamicconfig]: /docs/server-sdks/reference/python/agents/agent-base/set-dynamic-config-callback
+
+Remove all contexts from the agent, returning it to a no-contexts state. This is a
+convenience wrapper around [`define_contexts().reset()`][contextbuilderreset].
+
+Use it in a [dynamic config callback][setdynamicconfig] when you need to rebuild
+contexts from scratch for a specific request.
+
+## **Parameters**
+
+None.
+
+## **Returns**
+
+[`AgentBase`][ref-agentbase] -- Self for method chaining.
+
+## **Example**
+
+```python {5}
+from signalwire import AgentBase
+
+def on_dynamic_config(query, body, headers, agent):
+    if query.get("transfer"):
+        agent.reset_contexts()
+        ctx = agent.define_contexts().add_context("default")
+        ctx.add_step("route").set_text("Route the caller.")
+
+agent = AgentBase(name="router", route="/router")
+agent.set_dynamic_config_callback(on_dynamic_config)
+agent.serve()
+```

fern/products/server-sdks/pages/reference/python/agents/context-builder/context/index.mdx

@@ -90,6 +90,9 @@ You obtain a Context by calling `add_context()` on a ContextBuilder or by callin
   <Card title="set_full_reset" href="/docs/server-sdks/reference/python/agents/context-builder/context/set-full-reset">
     Set whether to completely replace the system prompt when entering this context.
   </Card>
+  <Card title="set_initial_step" href="/docs/server-sdks/reference/python/agents/context-builder/context/set-initial-step">
+    Set which step the context starts on when entered.
+  </Card>
   <Card title="set_isolated" href="/docs/server-sdks/reference/python/agents/context-builder/context/set-isolated">
     Set whether to truncate conversation history when entering this context.
   </Card>

fern/products/server-sdks/pages/reference/python/agents/context-builder/context/set-initial-step.mdx

@@ -0,0 +1,45 @@
+---
+title: "set_initial_step"
+slug: /reference/python/agents/context-builder/context/set-initial-step
+description: Set which step the context starts on when entered.
+max-toc-depth: 3
+---
+
+[ref-context]: /docs/server-sdks/reference/python/agents/context-builder/context
+[addstep]: /docs/server-sdks/reference/python/agents/context-builder/context/add-step
+
+Set which step the context starts on when entered. By default, a context starts on
+its first step (index `0`). When a context has a preamble step that should only run
+on first entry -- for example, a greeting -- later entries via `change_context` can
+skip it by setting `initial_step` to a different step name.
+
+`initial_step` is honoured both at conversation creation (when the context is first
+activated) and when switching to this context via `change_context` during the
+conversation.
+
+## **Parameters**
+
+<ParamField path="step_name" type="str" required={true} toc={true}>
+  Name of the step to start on. Must exist in this context's
+  [step list][addstep]; validated by `ContextBuilder.validate()`.
+</ParamField>
+
+## **Returns**
+
+[`Context`][ref-context] -- Self for method chaining.
+
+## **Example**
+
+```python {7}
+from signalwire import AgentBase
+
+agent = AgentBase(name="support", route="/support")
+contexts = agent.define_contexts()
+
+ctx = contexts.add_context("support")
+ctx.add_step("greeting").set_text("Welcome the caller to support.")
+ctx.add_step("triage").set_text("Ask what they need help with.")
+ctx.set_initial_step("triage")  # skip greeting on re-entry
+
+agent.serve()
+```

fern/products/server-sdks/pages/reference/python/agents/context-builder/index.mdx

@@ -10,6 +10,7 @@ max-toc-depth: 3
 [agentbase]: /docs/server-sdks/reference/python/agents/agent-base
 [addcontext]: /docs/server-sdks/reference/python/agents/context-builder/add-context
 [getcontext]: /docs/server-sdks/reference/python/agents/context-builder/get-context
+[reset]: /docs/server-sdks/reference/python/agents/context-builder/reset
 [todict]: /docs/server-sdks/reference/python/agents/context-builder/to-dict
 [validate]: /docs/server-sdks/reference/python/agents/context-builder/validate
 
@@ -45,6 +46,9 @@ automatically.
   <Card title="get_context" href="/docs/server-sdks/reference/python/agents/context-builder/get-context">
     Retrieve an existing context by name.
   </Card>
+  <Card title="reset" href="/docs/server-sdks/reference/python/agents/context-builder/reset">
+    Remove all contexts, returning the builder to its initial state.
+  </Card>
   <Card title="to_dict" href="/docs/server-sdks/reference/python/agents/context-builder/to-dict">
     Convert all contexts to a dictionary for SWML generation.
   </Card>

fern/products/server-sdks/pages/reference/python/agents/context-builder/reset.mdx

@@ -0,0 +1,43 @@
+---
+title: "reset"
+slug: /reference/python/agents/context-builder/reset
+description: Remove all contexts, returning the builder to its initial state.
+max-toc-depth: 3
+---
+
+[contextbuilder]: /docs/server-sdks/reference/python/agents/context-builder
+[resetcontexts]: /docs/server-sdks/reference/python/agents/agent-base/reset-contexts
+[setdynamicconfig]: /docs/server-sdks/reference/python/agents/agent-base/set-dynamic-config-callback
+
+Remove all contexts from the builder, returning it to its initial empty state. Use
+this in a [dynamic config callback][setdynamicconfig] when you need to rebuild
+contexts from scratch for a specific request -- for example, skipping a greeting
+context on transfers.
+
+For convenience at the agent level, see
+[`AgentBase.reset_contexts()`][resetcontexts], which wraps `define_contexts().reset()`.
+
+## **Parameters**
+
+None.
+
+## **Returns**
+
+[`ContextBuilder`][contextbuilder] -- Self for method chaining.
+
+## **Example**
+
+```python {6}
+from signalwire import AgentBase
+
+def on_dynamic_config(query, body, headers, agent):
+    if query.get("transfer"):
+        # Wipe the default contexts and rebuild for transfer flow
+        agent.define_contexts().reset()
+        ctx = agent.define_contexts().add_context("default")
+        ctx.add_step("route").set_text("Route the caller.")
+
+agent = AgentBase(name="router", route="/router")
+agent.set_dynamic_config_callback(on_dynamic_config)
+agent.serve()
+```

fern/products/server-sdks/pages/reference/python/rest/phone-numbers/index.mdx

@@ -1,7 +1,7 @@
 ---
 title: "Phone Numbers"
 slug: /reference/python/rest/phone-numbers
-description: "Search and manage phone numbers."
+description: "Search and manage phone numbers, and bind inbound calls to handlers."
 max-toc-depth: 3
 ---
 
@@ -12,10 +12,19 @@ max-toc-depth: 3
 [update]: /docs/server-sdks/reference/python/rest/phone-numbers/update
 [delete]: /docs/server-sdks/reference/python/rest/phone-numbers/delete
 [search]: /docs/server-sdks/reference/python/rest/phone-numbers/search
+[setswml]: /docs/server-sdks/reference/python/rest/phone-numbers/set-swml-webhook
+[setcxml]: /docs/server-sdks/reference/python/rest/phone-numbers/set-cxml-webhook
+[setcxmlapp]: /docs/server-sdks/reference/python/rest/phone-numbers/set-cxml-application
+[setai]: /docs/server-sdks/reference/python/rest/phone-numbers/set-ai-agent
+[setflow]: /docs/server-sdks/reference/python/rest/phone-numbers/set-call-flow
+[setrelayapp]: /docs/server-sdks/reference/python/rest/phone-numbers/set-relay-application
+[setrelaytopic]: /docs/server-sdks/reference/python/rest/phone-numbers/set-relay-topic
 
 Search for available phone numbers, purchase them, and manage the numbers in your
 SignalWire project. This resource extends the standard CRUD pattern with a `search()`
-method for discovering available numbers and uses PUT for updates.
+method for discovering available numbers, uses PUT for updates, and provides typed
+helpers for binding inbound calls to a handler (SWML webhook, cXML webhook, AI agent,
+call flow, RELAY application/topic).
 
 Access via `client.phone_numbers` on a [`RestClient`][restclient] instance.
 
@@ -35,6 +44,8 @@ for number in available.get("data", []):
 
 ## **Methods**
 
+### Standard CRUD
+
 <CardGroup cols={3}>
   <Card title="list" href="/docs/server-sdks/reference/python/rest/phone-numbers/list">
     List phone numbers owned by the project.
@@ -55,3 +66,66 @@ for number in available.get("data", []):
     Search for available phone numbers to purchase.
   </Card>
 </CardGroup>
+
+### Typed Binding Helpers
+
+Each helper is a one-line wrapper over [`update`][update] that sets `call_handler` to
+the right value and populates the handler-specific companion field for you. Pass extra
+keyword arguments through to `update` for fields the helper doesn't name explicitly.
+Setting a binding auto-materializes the matching Fabric resource on the server.
+
+<CardGroup cols={3}>
+  <Card title="set_swml_webhook" href="/docs/server-sdks/reference/python/rest/phone-numbers/set-swml-webhook">
+    Route inbound calls to an SWML webhook URL.
+  </Card>
+  <Card title="set_cxml_webhook" href="/docs/server-sdks/reference/python/rest/phone-numbers/set-cxml-webhook">
+    Route inbound calls to a cXML (LAML) webhook.
+  </Card>
+  <Card title="set_cxml_application" href="/docs/server-sdks/reference/python/rest/phone-numbers/set-cxml-application">
+    Route inbound calls to an existing cXML application by ID.
+  </Card>
+  <Card title="set_ai_agent" href="/docs/server-sdks/reference/python/rest/phone-numbers/set-ai-agent">
+    Route inbound calls to an AI Agent Fabric resource by ID.
+  </Card>
+  <Card title="set_call_flow" href="/docs/server-sdks/reference/python/rest/phone-numbers/set-call-flow">
+    Route inbound calls to a Call Flow by ID.
+  </Card>
+  <Card title="set_relay_application" href="/docs/server-sdks/reference/python/rest/phone-numbers/set-relay-application">
+    Route inbound calls to a named RELAY application.
+  </Card>
+  <Card title="set_relay_topic" href="/docs/server-sdks/reference/python/rest/phone-numbers/set-relay-topic">
+    Route inbound calls to a RELAY topic.
+  </Card>
+</CardGroup>
+
+## **PhoneCallHandler enum**
+
+For callers passing `call_handler` directly to [`update`][update], the
+`PhoneCallHandler` enum provides typed values. Each member is a `str` subclass, so
+passing the enum member serializes to the wire value without `.value` indirection.
+
+```python
+from signalwire.rest import PhoneCallHandler
+
+client.phone_numbers.update(
+    "phone-number-id",
+    call_handler=PhoneCallHandler.AI_AGENT,
+    call_ai_agent_id="ai-agent-id",
+)
+```
+
+| Enum member        | Wire value           | Companion field            | Auto-creates        |
+|--------------------|----------------------|----------------------------|---------------------|
+| `RELAY_SCRIPT`     | `relay_script`       | `call_relay_script_url`    | `swml_webhook`      |
+| `LAML_WEBHOOKS`    | `laml_webhooks`      | `call_request_url`         | `cxml_webhook`      |
+| `LAML_APPLICATION` | `laml_application`   | `call_laml_application_id` | `cxml_application`  |
+| `AI_AGENT`         | `ai_agent`           | `call_ai_agent_id`         | `ai_agent`          |
+| `CALL_FLOW`        | `call_flow`          | `call_flow_id`             | `call_flow`         |
+| `RELAY_APPLICATION`| `relay_application`  | `call_relay_application`   | `relay_application` |
+| `RELAY_TOPIC`      | `relay_topic`        | `call_relay_topic`         | (routes via RELAY)  |
+
+<Note>
+`LAML_WEBHOOKS` (wire value `laml_webhooks`) produces a **cXML** handler, not a
+generic webhook. For SWML, use `RELAY_SCRIPT` -- or, more conveniently, the
+[`set_swml_webhook`][setswml] helper.
+</Note>

fern/products/server-sdks/pages/reference/python/rest/phone-numbers/set-ai-agent.mdx

@@ -0,0 +1,49 @@
+---
+title: "set_ai_agent"
+slug: /reference/python/rest/phone-numbers/set-ai-agent
+description: Route inbound calls to an AI Agent Fabric resource by ID.
+max-toc-depth: 3
+---
+
+[update]: /docs/server-sdks/reference/python/rest/phone-numbers/update
+
+Route inbound calls on this phone number to an existing AI Agent Fabric resource by
+its ID.
+
+This is a typed wrapper over [`update`][update] that sets `call_handler` to
+`ai_agent` and populates `call_ai_agent_id` for you.
+
+## **Parameters**
+
+<ParamField path="resource_id" type="str" required={true} toc={true}>
+  ID of the phone number to bind.
+</ParamField>
+
+<ParamField path="agent_id" type="str" required={true} toc={true}>
+  ID of the AI Agent Fabric resource to route calls to.
+</ParamField>
+
+<ParamField path="**extra" type="Any" toc={true}>
+  Additional fields forwarded to `update`.
+</ParamField>
+
+## **Returns**
+
+`dict` -- The updated phone number resource.
+
+## **Example**
+
+```python {9}
+from signalwire.rest import RestClient
+
+client = RestClient(
+    project="your-project-id",
+    token="your-api-token",
+    host="your-space.signalwire.com",
+)
+
+client.phone_numbers.set_ai_agent(
+    "phone-number-id",
+    "ai-agent-id",
+)
+```

fern/products/server-sdks/pages/reference/python/rest/phone-numbers/set-call-flow.mdx

@@ -0,0 +1,55 @@
+---
+title: "set_call_flow"
+slug: /reference/python/rest/phone-numbers/set-call-flow
+description: Route inbound calls to a Call Flow by ID.
+max-toc-depth: 3
+---
+
+[update]: /docs/server-sdks/reference/python/rest/phone-numbers/update
+
+Route inbound calls on this phone number to an existing Call Flow by its ID.
+
+This is a typed wrapper over [`update`][update] that sets `call_handler` to
+`call_flow` and populates `call_flow_id` for you.
+
+## **Parameters**
+
+<ParamField path="resource_id" type="str" required={true} toc={true}>
+  ID of the phone number to bind.
+</ParamField>
+
+<ParamField path="flow_id" type="str" required={true} toc={true}>
+  ID of the Call Flow to route calls to.
+</ParamField>
+
+<ParamField path="version" type="Optional[str]" toc={true}>
+  Which Call Flow version to invoke. Accepts `"working_copy"` or
+  `"current_deployed"`. Defaults to the server's current deployed version when
+  omitted.
+</ParamField>
+
+<ParamField path="**extra" type="Any" toc={true}>
+  Additional fields forwarded to `update`.
+</ParamField>
+
+## **Returns**
+
+`dict` -- The updated phone number resource.
+
+## **Example**
+
+```python {9}
+from signalwire.rest import RestClient
+
+client = RestClient(
+    project="your-project-id",
+    token="your-api-token",
+    host="your-space.signalwire.com",
+)
+
+client.phone_numbers.set_call_flow(
+    "phone-number-id",
+    "call-flow-id",
+    version="working_copy",
+)
+```