courier-encode 0.1.3__tar.gz → 0.1.4__tar.gz

{courier_encode-0.1.3 → courier_encode-0.1.4}/.idea/workspace.xml

@@ -7,13 +7,14 @@
     <list default="true" id="9259bfb5-884c-4336-83fd-f640b45e88c5" name="Changes" comment="">
       <change beforePath="$PROJECT_DIR$/README.md" beforeDir="false" afterPath="$PROJECT_DIR$/README.md" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/docs.md" beforeDir="false" afterPath="$PROJECT_DIR$/docs.md" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/pyproject.toml" beforeDir="false" afterPath="$PROJECT_DIR$/pyproject.toml" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/src/encode/__init__.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/encode/__init__.py" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/src/encode/errors.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/encode/errors.py" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/src/encode/messages.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/encode/messages.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/docs/cookbook.md" beforeDir="false" afterPath="$PROJECT_DIR$/docs/cookbook.md" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/docs/intercept.md" beforeDir="false" afterPath="$PROJECT_DIR$/docs/intercept.md" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/docs/sessions.md" beforeDir="false" afterPath="$PROJECT_DIR$/docs/sessions.md" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/docs/tools.md" beforeDir="false" afterPath="$PROJECT_DIR$/docs/tools.md" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/encode/events.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/encode/events.py" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/src/encode/relay.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/encode/relay.py" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/src/encode/session.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/encode/terminal.py" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/tests/test_session.py" beforeDir="false" afterPath="$PROJECT_DIR$/tests/test_terminal.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/encode/session.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/encode/session.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/encode/tools.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/encode/tools.py" afterDir="false" />
     </list>
     <option name="SHOW_DIALOG" value="false" />
     <option name="HIGHLIGHT_CONFLICTS" value="true" />
@@ -21,7 +22,7 @@
     <option name="LAST_RESOLUTION" value="IGNORE" />
   </component>
   <component name="EmbeddingIndexingInfo">
-    <option name="cachedIndexableFilesCount" value="52" />
+    <option name="cachedIndexableFilesCount" value="77" />
     <option name="fileBasedEmbeddingIndicesEnabled" value="true" />
   </component>
   <component name="Git.Settings">
@@ -83,7 +84,18 @@
       <workItem from="1778423372046" duration="273000" />
       <workItem from="1778423984110" duration="32000" />
       <workItem from="1778512211978" duration="598000" />
-      <workItem from="1778554267806" duration="729000" />
+      <workItem from="1778554267806" duration="2737000" />
+      <workItem from="1778562018820" duration="121000" />
+      <workItem from="1778562226220" duration="194000" />
+      <workItem from="1778562580231" duration="10000" />
+      <workItem from="1778562812770" duration="145000" />
+      <workItem from="1778563167441" duration="597000" />
+      <workItem from="1778563885595" duration="136000" />
+      <workItem from="1778564171039" duration="6000" />
+      <workItem from="1778565065245" duration="21000" />
+      <workItem from="1778566926702" duration="15000" />
+      <workItem from="1778567092312" duration="17000" />
+      <workItem from="1778617494707" duration="2069000" />
     </task>
     <servers />
   </component>

{courier_encode-0.1.3 → courier_encode-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: courier-encode
-Version: 0.1.3
+Version: 0.1.4
 Summary: Python SDK for OpenAI-compatible inference endpoints (Courier and friends) with auto tool-call loops, structured outputs, and Whisper.
 Project-URL: Homepage, https://getcourier.ai
 Project-URL: Documentation, https://getcourier.ai/docs
@@ -359,6 +359,21 @@ def trim(event):
 encode.relay(..., tools=[noisy_tool], on_intercept=trim).response
 ```
 
+**Auto tool discovery** — the model calls a `list_tools` bootstrap, an intercept registers the discovered tools on the session, the next iteration uses them.
+
+```python
+session = encode.Session.open(tools=[list_tools])
+
+def discover(event):
+    for tc in event.tool_calls:
+        if tc.name == "list_tools":
+            for spec in tc.result or []:
+                event.register_tool(IMPLS[spec["function"]["name"]])
+
+encode.relay(model="m", messages=[...], session=session,
+             tools=session.tools, on_intercept=discover).response
+```
+
 **A bash sandbox tool.**
 
 ```python

{courier_encode-0.1.3 → courier_encode-0.1.4}/README.md

@@ -123,6 +123,21 @@ def trim(event):
 encode.relay(..., tools=[noisy_tool], on_intercept=trim).response
 ```
 
+**Auto tool discovery** — the model calls a `list_tools` bootstrap, an intercept registers the discovered tools on the session, the next iteration uses them.
+
+```python
+session = encode.Session.open(tools=[list_tools])
+
+def discover(event):
+    for tc in event.tool_calls:
+        if tc.name == "list_tools":
+            for spec in tc.result or []:
+                event.register_tool(IMPLS[spec["function"]["name"]])
+
+encode.relay(model="m", messages=[...], session=session,
+             tools=session.tools, on_intercept=discover).response
+```
+
 **A bash sandbox tool.**
 
 ```python

{courier_encode-0.1.3 → courier_encode-0.1.4}/docs/cookbook.md

@@ -310,6 +310,60 @@ for w in out.words or []:
 
 ---
 
+## Auto tool discovery — `list_tools` + intercept
+
+Single bootstrap tool, intercept appends discovered tools, the model uses them on the next turn — no restarts.
+
+```python
+import encode
+
+def list_tools() -> list[dict]:
+    """Discover available tools."""
+    return [
+        {"type": "function", "function": {
+            "name": "fetch",
+            "description": "Fetch a URL.",
+            "parameters": {
+                "type": "object",
+                "properties": {"url": {"type": "string"}},
+                "required": ["url"],
+                "additionalProperties": False,
+            },
+        }},
+    ]
+
+def fetch(url: str) -> dict:
+    """Fetch a URL."""
+    return {"url": url, "status": 200}
+
+IMPLS = {"fetch": fetch}
+
+def discover(event):
+    for tc in event.tool_calls:
+        if tc.name == "list_tools":
+            for spec in tc.result or []:
+                name = spec["function"]["name"]
+                if name in IMPLS:
+                    event.register_tool(IMPLS[name])
+
+session = encode.Session.open(tools=[list_tools])
+out = encode.relay(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "Discover tools, then fetch example.com."}],
+    session=session,
+    tools=session.tools,
+    on_intercept=discover,
+    max_tool_iterations=10,
+).response
+
+print(out.content)
+print("registered:", [ev.data["name"] for ev in session.events_by_type("tool.registered")])
+```
+
+Source: [`examples/tool_discovery.py`](../examples/tool_discovery.py) — [sessions.md](./sessions.md#session-owned-tools), [intercept.md](./intercept.md#auto-tool-discovery--eventregister_toolfn)
+
+---
+
 ## Branching conversations
 
 ```python

{courier_encode-0.1.3 → courier_encode-0.1.4}/docs/intercept.md

@@ -176,6 +176,53 @@ await encode.relay_async(...).intercept(cb)
 
 Async callbacks can still call the sync mutation helpers — they operate on the in-memory `Messages` view.
 
+## Auto tool discovery — `event.register_tool(fn)`
+
+When `session=` is attached to the run, the intercept callback can register a new tool on the session's append-only registry, and the **next** iteration of the loop will see it. This unlocks a clean auto-discovery pattern: the model calls a bootstrap `list_tools` function, the intercept reads the result, and the model proceeds to call the freshly registered tools without restarting the run.
+
+```python
+def list_tools() -> list[dict]:
+    """Discover available tools."""
+    return [
+        {"type": "function", "function": {"name": "fetch", "description": "...",
+         "parameters": {...}}},
+    ]
+
+def fetch(url: str) -> dict:
+    """Fetch a URL."""
+    ...
+
+IMPLS = {"fetch": fetch}
+
+def discover(event):
+    for tc in event.tool_calls:
+        if tc.name != "list_tools":
+            continue
+        for spec in tc.result or []:
+            name = spec["function"]["name"]
+            if name in IMPLS:
+                event.register_tool(IMPLS[name])    # binds callable for dispatch
+
+session = encode.Session.open(tools=[list_tools])
+encode.relay(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "discover, then use what you find"}],
+    session=session,
+    tools=session.tools,                # ← live registry
+    on_intercept=discover,
+).response
+```
+
+Rules:
+
+- `event.register_tool(tool)` requires the run to have a `session=`. Otherwise it raises.
+- Idempotent: a same-name registration is a no-op. Returns `True` if newly registered, `False` if skipped.
+- Each registration emits a `tool.registered` event into the session log with `by="intercept"`.
+- For the new tool to appear in the model's next iteration, you must have passed `tools=session.tools` to `relay()` (so the relay loop is reading from the same list the intercept mutates).
+- Works on both the chat and responses endpoints, and across streaming + non-streaming.
+
+See [sessions.md → Session-owned tools](./sessions.md#session-owned-tools) for the registry API itself (`register_tool` / `register_tools` / `rebind_tools` / `Session.resume`).
+
 ## Cookbook — full agent + stop()
 
 ```python

{courier_encode-0.1.3 → courier_encode-0.1.4}/docs/sessions.md

@@ -67,6 +67,7 @@ Standard types (`EventType.*`):
 | `ASSISTANT_MESSAGE` | `assistant.message` | `{"content": str | None, "tool_calls": [...] | None}`     |
 | `TOOL_CALL`         | `tool.call`      | `{"id": str, "name": str, "arguments": dict, "iteration": int}` |
 | `TOOL_RESULT`       | `tool.result`    | `{"id": str, "result": Any, "result_serialized": str, "error": str | None, "duration_ms": float}` |
+| `TOOL_REGISTERED`   | `tool.registered` | `{"name": str, "schema": dict, "by": str}` (emitted by `register_tool` / `Session.open(tools=...)` / `rebind_tools`) |
 | `ITERATION_END`     | `iteration.end`  | `{"iteration": int, "had_tool_calls": bool, "finish_reason": str | None}` |
 | `CONTEXT_MODIFY`    | `context.modify` | `{"by": str, "summary": str, ...}` (emitted by Intercept mutations) |
 | `SYSTEM`            | `system`         | `{"content": str}`                                           |
@@ -200,6 +201,76 @@ Recommended patterns:
 - **Single writer**: one process owns the in-memory `Session`; persist after each `relay()` call.
 - **Atomic append at the DB layer**: write events one at a time (e.g. `INSERT` with serial id from a sequence) and rehydrate before each `relay()`.
 
+## Session-owned tools
+
+A Session can also own an **append-only tool registry** — pass `tools=session.tools` to `relay()` and you can grow the registry mid-loop (typically from an intercept callback) so a single agent run can discover and start using new tools without re-launching.
+
+```python
+def search(query: str) -> dict:
+    """Search the index."""
+    return ...
+
+def list_tools() -> list[dict]:
+    """Discover available tools."""
+    return [...]   # tool schemas as raw dicts
+
+session = encode.Session.open(tools=[search, list_tools])
+
+encode.relay(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "discover, then use what you find"}],
+    session=session,
+    tools=session.tools,        # ← the live registry
+    on_intercept=lambda ev: [ev.register_tool(s) for tc in ev.tool_calls
+                             if tc.name == "list_tools" for s in (tc.result or [])],
+).response
+```
+
+API:
+
+```python
+session.register_tool(fn_or_dict)           # idempotent: same name → no-op, returns False
+session.register_tools([fn1, fn2, ...])     # bulk, returns count newly added
+session.tools                               # list[Any] — the live registry
+```
+
+Each `register_tool` call emits a `tool.registered` event into the durable log; the `by` field records the origin (`"user"`, `"intercept"`, `"resume"`).
+
+### How auto-discovery flows through the loop
+
+The relay loop re-reads `tools=` at the top of each iteration. When it's the same list reference as `session.tools`, additions made during an intercept callback show up on the **next** iteration's request to the model. The in-process executor's dispatch table is also rebuilt automatically — your registered callable is callable next turn.
+
+If you pass a different list as `tools=` (i.e. not `session.tools`), `event.register_tool(...)` still appends to the session and emits the audit-log event, but the new tool won't appear in the model's next request — pass `tools=session.tools` to opt in.
+
+### Idempotency
+
+Same-name registrations are silently skipped. This makes auto-discovery loops safe to re-trigger: if the model calls `list_tools` twice and returns overlapping specs, only the new names are registered. Both `register_tool(fn)` and `register_tools([...])` return how many entries were *newly* added.
+
+### Resuming with tools
+
+`session.model_dump()` does **not** include the live `tools` list — Python callables aren't JSON-serializable. The `tool.registered` events are part of the log, though, so they survive the round-trip. Use `rebind_tools` (or the `Session.resume` convenience class method) to bind your callables back to the session on the other side:
+
+```python
+# round-trip — anything that survives JSON works
+raw = json.dumps(session.model_dump(), default=str)
+
+# Method 1: one-liner via Session.resume
+session = encode.Session.resume(json.loads(raw), tools=[search, list_tools])
+
+# Method 2: split into validate + rebind
+session = encode.Session.model_validate(json.loads(raw))
+missing = session.rebind_tools([search, list_tools])
+if missing:
+    print(f"missing callables for: {missing}")   # names from the log without a binding
+
+# Continue the run
+encode.relay(model="m", messages=[...], session=session, tools=session.tools).response
+```
+
+`rebind_tools` walks `tool.registered` events in order, matches each name against the callables you supplied (by `__name__` for functions, `function.name` / `name` for dicts), and registers them with `by="resume"`. It's idempotent: calling it twice on the same session is safe.
+
+Async parity: `aregister_tool` / `aregister_tools` / `arebind_tools` on `AsyncSession`, and `AsyncSession.resume`.
+
 ## Custom events
 
 Emit whatever you want. Useful for application-level audit:

{courier_encode-0.1.3 → courier_encode-0.1.4}/docs/tools.md

@@ -173,9 +173,23 @@ def with_objects(q: str) -> dict:          # default=str handles datetimes etc.
     return {"created_at": datetime.now(), "rows": 3}
 ```
 
+## Tools that live on a Session
+
+Tools can also be stored on a `Session` — pass `tools=session.tools` to `relay()` and an intercept handler can append new tools mid-loop (auto-discovery). The session keeps an append-only `tool.registered` audit log. Idempotent: same-name registrations are no-ops.
+
+```python
+session = encode.Session.open(tools=[search])
+session.register_tool(fetch)                   # appends + emits tool.registered
+
+encode.relay(model="m", messages=[...], session=session, tools=session.tools).response
+```
+
+See [sessions.md → Session-owned tools](./sessions.md#session-owned-tools) and [intercept.md → Auto tool discovery](./intercept.md#auto-tool-discovery--eventregister_toolfn).
+
 ## See also
 
 - [intercept.md](./intercept.md) — observe / mutate between iterations
+- [sessions.md](./sessions.md) — session-owned tool registry
 - [executors.md](./executors.md) — swap dispatch (remote, MCP, sub-agent)
 - [terminal.md](./terminal.md) — the canonical stateful tool pattern
 - [errors.md](./errors.md) — `MaxToolIterationsError`, `InvalidToolCallError`

{courier_encode-0.1.3 → courier_encode-0.1.4}/docs.md

@@ -87,18 +87,32 @@ RelayHandle.execute()            # run, return RelayResponse
 RelayHandle.response             # property: run + memoize
 iter(RelayHandle)                # stream events
 
+# Intercept (mutable mid-loop)
+event.append/.insert/.replace/.compact/.edit_last_tool_result   # mutate messages
+event.stop()                                                     # halt the loop
+event.register_tool(fn_or_dict)                                  # session-required
+
 AsyncRelayHandle.intercept(cb)
 await AsyncRelayHandle           # awaitable directly
 await AsyncRelayHandle.execute()
 async for event in AsyncRelayHandle: ...
 
 # Sessions (durable event log)
-encode.Session.open(id=None, metadata=None)
+encode.Session.open(id=None, metadata=None, tools=None)
+encode.Session.resume(data, tools=())     # model_validate + rebind_tools
 encode.AsyncSession.open(...)
+encode.AsyncSession.resume(data, tools=())
+# Per-session tool registry (append-only, idempotent by name)
+session.tools                              # list[Any], excluded from model_dump
+session.register_tool(fn_or_dict)          # returns True if newly added
+session.register_tools([...])              # bulk, returns count newly added
+session.rebind_tools([...])                # returns list[str] of unmatched names
 encode.Event              # factory classmethods: user_message, assistant_message,
-                          # tool_call, tool_result, iteration_end, system, custom, ...
+                          # tool_call, tool_result, tool_registered, iteration_end,
+                          # system, custom, ...
 encode.EventType          # USER_MESSAGE, ASSISTANT_MESSAGE, TOOL_CALL, TOOL_RESULT,
-                          # ITERATION_END, CONTEXT_MODIFY, SYSTEM, CUSTOM
+                          # TOOL_REGISTERED, ITERATION_END, CONTEXT_MODIFY, SYSTEM,
+                          # CUSTOM
 
 # Executors (the brain↔hands seam)
 encode.ToolExecutor                       # Protocol

courier_encode-0.1.4/examples/tool_discovery.py

@@ -0,0 +1,120 @@
+"""Auto tool discovery via Session-owned tools + intercept.
+
+Pattern: the model has a single bootstrap tool (`list_tools`) that returns
+specs for additional tools. An intercept handler reads those specs, calls
+``event.register_tool(...)`` to append them to the session's append-only
+tool registry, and the *next* iteration of the relay loop sees them — the
+model can immediately call them.
+
+Run against any OpenAI-compatible endpoint with ENCODE_API_KEY +
+ENCODE_BASE_URL set; pick a model that supports tool-calling. The print
+statements below show the discovery flow.
+"""
+
+from __future__ import annotations
+
+import encode
+
+# --- the bootstrap tool ---
+
+
+def list_tools() -> list[dict]:
+    """List tools that can be registered on this session.
+
+    Returns OpenAI-style tool schemas. Pair with an intercept handler that
+    calls ``event.register_tool(spec)`` so the model sees them next turn.
+    """
+    return [
+        {
+            "type": "function",
+            "function": {
+                "name": "fetch",
+                "description": "Fetch a URL and return its body.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"url": {"type": "string"}},
+                    "required": ["url"],
+                    "additionalProperties": False,
+                },
+            },
+        },
+        {
+            "type": "function",
+            "function": {
+                "name": "summarize",
+                "description": "Summarize a block of text.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"text": {"type": "string"}},
+                    "required": ["text"],
+                    "additionalProperties": False,
+                },
+            },
+        },
+    ]
+
+
+# --- the actual implementations (registered as callables once discovered) ---
+
+
+def fetch(url: str) -> dict:
+    """Fetch a URL."""
+    # placeholder — wire up httpx in real code
+    return {"url": url, "status": 200, "body": "..."}
+
+
+def summarize(text: str) -> dict:
+    """Summarize text."""
+    return {"summary": text[:80]}
+
+
+IMPLS = {"fetch": fetch, "summarize": summarize}
+
+
+def discover(event: encode.InterceptEvent) -> None:
+    """Intercept handler: register discovered tools on the session."""
+    for tc in event.tool_calls:
+        if tc.name != "list_tools":
+            continue
+        for spec in tc.result or []:
+            name = spec.get("function", {}).get("name") or ""
+            impl = IMPLS.get(name)
+            if impl is None:
+                # we don't have a Python implementation — skip
+                continue
+            registered = event.register_tool(impl)
+            if registered:
+                print(f"  ↳ discovered + registered: {name}")
+
+
+def main() -> None:
+    session = encode.Session.open(tools=[list_tools])
+
+    out = encode.relay(
+        model="gpt-4o-mini",
+        messages=[
+            {
+                "role": "user",
+                "content": (
+                    "Discover the tools available to you, then fetch "
+                    "https://example.com and summarize the body."
+                ),
+            }
+        ],
+        session=session,
+        tools=session.tools,
+        on_intercept=discover,
+        max_tool_iterations=10,
+    ).response
+
+    print()
+    print("final answer:", out.content)
+    print("iterations:", out.iterations)
+    print(
+        "registered tools (final):",
+        [ev.data["name"] for ev in session.events_by_type("tool.registered")],
+    )
+
+
+if __name__ == "__main__":
+    main()

{courier_encode-0.1.3 → courier_encode-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "courier-encode"
-version = "0.1.3"
+version = "0.1.4"
 description = "Python SDK for OpenAI-compatible inference endpoints (Courier and friends) with auto tool-call loops, structured outputs, and Whisper."
 readme = "README.md"
 requires-python = ">=3.10"

{courier_encode-0.1.3 → courier_encode-0.1.4}/src/encode/events.py

@@ -32,6 +32,7 @@ class EventType:
     ASSISTANT_MESSAGE = "assistant.message"
     TOOL_CALL = "tool.call"
     TOOL_RESULT = "tool.result"
+    TOOL_REGISTERED = "tool.registered"
     ITERATION_END = "iteration.end"
     CONTEXT_MODIFY = "context.modify"
     SYSTEM = "system"
@@ -52,6 +53,7 @@ class Event(BaseModel):
     - ``tool.call``         : ``{"id": str, "name": str, "arguments": dict, "iteration": int}``
     - ``tool.result``       : ``{"id": str, "result": Any, "result_serialized": str,
                                   "error": str | None, "duration_ms": float}``
+    - ``tool.registered``   : ``{"name": str, "schema": dict, "by": str}``
     - ``iteration.end``     : ``{"iteration": int, "had_tool_calls": bool,
                                   "finish_reason": str | None}``
     - ``context.modify``    : ``{"by": str, "summary": str, ...}``
@@ -127,6 +129,19 @@ class Event(BaseModel):
             },
         )
 
+    @classmethod
+    def tool_registered(
+        cls,
+        *,
+        name: str,
+        schema: dict[str, Any],
+        by: str = "user",
+    ) -> Event:
+        return cls(
+            type=EventType.TOOL_REGISTERED,
+            data={"name": name, "schema": dict(schema), "by": by},
+        )
+
     @classmethod
     def iteration_end(
         cls,