[codex] add python sdk examples

[calvin-archastro]

What changed

Adds three public Python SDK examples with focused test coverage:

• examples/org_system_user_token: shows how an ArchAgents org-owned system user can use the SDK with only ARCHASTRO_ACCESS_TOKEN. The README covers sync and async client setup, the ArchAgents archagent path, developer bootstrap with archastro, and token rotation.
• examples/create_agent_cli: shows a small sync CLI wrapper around PlatformClient.with_token(...) for creating an agent.
• examples/thread_chat_tui: shows a basic curses chat UI for an existing thread using AsyncPlatformClient.open_socket(...) and generated chat channel helpers.

Updates the root README with a public getting-started flow for ArchAgents use cases, including system-user token setup, sync PlatformClient usage, async AsyncPlatformClient usage, developer app auth, and links to the examples.

The TUI keeps websocket operations in ThreadChatSession and terminal rendering/input in ThreadChatTui, so the SDK usage remains visible without coupling curses UI code directly to generated channel calls.

CI now includes tests/examples in the unit-test slice, and the root README documents how to run those example tests locally.

Diagrams

sequenceDiagram
    participant Operator as SDK user
    participant CLI as create agent example
    participant SyncClient as PlatformClient
    participant API as production API gateway

    Operator->>CLI: run with name identity and env tokens
    CLI->>SyncClient: with_token using API key and access token
    SyncClient->>API: POST create agent
    API-->>SyncClient: created agent payload
    SyncClient-->>CLI: agent data
    CLI-->>Operator: print JSON result

Loading

sequenceDiagram
    participant User as terminal user
    participant TUI as ThreadChatTui
    participant Session as ThreadChatSession
    participant AsyncClient as AsyncPlatformClient
    participant Channel as ApiChatChannel
    participant API as production API gateway

    User->>TUI: type message and press Enter
    TUI->>Session: send_message with idempotency key
    Session->>Channel: api_chat_post_simple_message
    Channel->>API: websocket push
    API-->>Channel: ok reply
    Channel-->>Session: reply
    Session-->>TUI: send complete
    TUI-->>User: show Message sent

Loading

classDiagram
    class PlatformClient {
        +with_token(api_key access_token base_url)
        +agents
        +users
    }
    class AsyncPlatformClient {
        +open_socket(url)
        +users
    }
    class ThreadChatSession {
        +on_message_added(callback)
        +load_history()
        +send_message(content idempotency_key)
        +close()
    }
    class ThreadChatTui {
        +add_history(messages)
        +add_message_payload(payload)
        +run()
    }
    class ApiChatChannel {
        +join_user_thread(socket thread_id)
        +join_team_thread(socket team_id thread_id)
        +api_chat_list_messages(payload)
        +api_chat_post_simple_message(payload)
        +leave()
    }
    PlatformClient ..> API : sync REST
    AsyncPlatformClient ..> ApiChatChannel : opens socket for
    ThreadChatSession ..> ApiChatChannel : wraps
    ThreadChatTui ..> ThreadChatSession : uses

Loading

Scope indicator

SDK docs, examples, and CI only. No generated SDK runtime files or backend/frontend application code changed.

Risk assessment

Low risk. This adds opt-in example scripts and tests, plus includes those tests in the existing CI unit-test command. The only runtime-adjacent change is example code under examples/.

User impact

SDK users get a root README quickstart for ArchAgents system-user use cases plus runnable examples for common usage patterns: system-user auth, sync REST calls, async REST calls, creating agents from a CLI, and websocket chat in a terminal UI.

Testing

Automated checks run locally:

• uv run ruff check
• uv run ruff format --check
• uv run pytest tests/examples -p no:cacheprovider with 12 passed
• uv run pytest tests/test_http_client.py src/archastro/phx_channel/tests/test_unit.py tests/examples -p no:cacheprovider with 63 passed

Manual/local smoke checks performed against the local platform before opening this PR:

• System-user example created a local org system user token and printed the expected authenticated system user.
• Create-agent example created agi_033XIHg5RXvKReEbG8kxns and CLI readback matched the returned payload.
• Thread TUI sent msg_033XIPDIpEosVpdUMA5Eqp through the real curses UI and CLI readback found the message in the thread.

Follow-ups and known issues

No known issues. The example docs avoid internal service names and only mention production defaults plus public local or non-production override behavior.

[archastro]

✅ Clean PR, @calvin-archastro! No blocking findings on 2e7ae77 — a few nice things I clocked:

• Clean separation of concerns in thread_chat_tui/main.py — ThreadChatSession owns the websocket/ApiChatChannel calls while ThreadChatTui owns curses render/input, keeping the SDK flow legible. ✨
• Nice optimistic-send handling — _post_message stamps a uuid4 idempotency_key and _append_or_replace dedups by idempotency_key/id, so server echo and local pending message reconcile cleanly. 🎯
• Solid failure-mode coverage — test_chat_closes_client_when_leave_raises and test_draw_avoids_bottom_right_curses_cell lock in the cleanup-on-error and curses bottom-right-cell edge cases, not just the happy path. 🙌

---

_{Reply @archastro <verb>: review · do <pattern> · don't <pattern> · forget <slug> · list}