smooai-smooth-operator-server 1.23.1__tar.gz

smooai_smooth_operator_server-1.23.1/.gitignore

@@ -0,0 +1,41 @@
+# Rust
+target/
+**/*.rs.bk
+# Cargo.lock IS committed: this workspace ships a binary (smooth-operator-server)
+# and the Dockerfile builds with `cargo build --locked`, which requires it.
+
+# Node / TypeScript
+node_modules/
+dist/
+*.tsbuildinfo
+.turbo/
+
+# Go
+/go/bin/
+
+# .NET
+bin/
+obj/
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+.mypy_cache/
+.ruff_cache/
+
+# SST / deploy
+.sst/
+.open-next/
+cdk.out/
+
+# Env / secrets
+.env
+.env.local
+*.pem
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/*
+!.vscode/extensions.json

smooai_smooth_operator_server-1.23.1/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: smooai-smooth-operator-server
+Version: 1.23.1
+Summary: Native async WebSocket server for the smooth-operator protocol — parity with the Rust and C# reference servers, consuming the in-process smooai-smooth-operator-core engine.
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: smooai-smooth-operator-core>=1.3.2
+Requires-Dist: websockets>=12
+Provides-Extra: gateway
+Requires-Dist: openai>=1.40; extra == 'gateway'
+Description-Content-Type: text/markdown
+
+# smooai-smooth-operator-server
+
+<p>
+  <a href="https://smoo.ai"><img src="https://img.shields.io/badge/Smoo_AI-platform-00A6A6?style=for-the-badge&labelColor=020618" alt="Smoo AI"></a>
+  <a href="https://github.com/SmooAI/smooth-operator/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-FF6B6C?style=for-the-badge&labelColor=020618" alt="license"></a>
+  <a href="https://www.python.org"><img src="https://img.shields.io/badge/Python-%E2%89%A53.11-00A6A6?style=for-the-badge&labelColor=020618" alt="Python ≥ 3.11"></a>
+</p>
+
+**Wiring a chat loop is a weekend project. A production agent _server_ is not.**
+
+Sessions that survive a reconnect. A wire protocol your clients can actually speak. Streaming turns you can watch token by token. Tools the model can call — and hard limits on the ones it must never call. Human-in-the-loop when a tool wants to write.
+
+`smooai-smooth-operator-server` is that server, async and native to Python. It speaks the [smooth-operator](https://github.com/SmooAI/smooth-operator) wire protocol ([`spec/`](https://github.com/SmooAI/smooth-operator/tree/main/spec)) and consumes the in-process [`smooai-smooth-operator-core`](https://pypi.org/project/smooai-smooth-operator-core/) engine — each turn runs a `SmoothAgent` and maps its stream onto `stream_token` / `stream_chunk` / `eventual_response`. It's the Python sibling of the [Rust](../../rust/smooth-operator-server), [Go](../../go/server), [TypeScript](../../typescript/server), and [C#](../../dotnet/server) servers, all speaking the one protocol.
+
+> The client lives in [`python/src`](../src) (`smooai-smooth-operator`). This is the **server** half.
+
+---
+
+## Spin up a real agent server
+
+```bash
+python -m smooth_operator_server
+# → smooth-operator-server (local flavor, python) listening on ws://127.0.0.1:8787/ws
+```
+
+That's a full agent backend — sessions, streaming turns, tool-calling, citations — on one WebSocket, in-memory, auth off, zero config. Env knobs: `SMOOTH_OPERATOR_BIND` (default `127.0.0.1:8787`), `SMOOTH_OPERATOR_SEED_KB=1` for the demo knowledge docs. The gateway is read from `SMOOAI_GATEWAY_URL` / `SMOOAI_GATEWAY_KEY` — with no key, `send_message` returns a clean `LLM_UNAVAILABLE` error and the rest of the protocol still works.
+
+Or embed it in your own async app:
+
+```python
+import asyncio
+from smooth_operator_server import ServerState, serve
+from smooth_operator_server.session_store import InMemorySessionStore
+
+async def main():
+    state = ServerState(store=InMemorySessionStore(), chat_client=my_openai_client)
+    server = await serve(state, "127.0.0.1", 0)  # port 0 → ephemeral
+    print(server.ws_url())
+    # ... drive real streaming turns ...
+    await server.shutdown()  # graceful drain + clean exit
+
+asyncio.run(main())
+```
+
+---
+
+## Extensible — and safe by construction
+
+An agent is only useful when it can *do* things, and only trustworthy when you can say what it may never do. This server gives you both seams.
+
+**Give it your tools.** Hand engine `Tool`s to `ServerState` and they merge with the built-ins for every turn:
+
+```python
+from smooth_operator_core import Tool  # the engine's tool base
+
+class OpenTicket(Tool):
+    name = "open_ticket"
+    description = "Open a support ticket for the current customer."
+    parameters = {"type": "object", "properties": {"subject": {"type": "string"}}}
+
+    async def execute(self, arguments):
+        return f"ticket opened: {arguments}"
+
+state = ServerState(
+    store=InMemorySessionStore(),
+    chat_client=my_client,
+    tools=[OpenTicket()],
+)
+```
+
+**Or let it gain tools with no redeploy.** The server hosts [SEP extensions](https://github.com/SmooAI/smooth-operator/blob/main/docs/TOOLS.md) — out-of-process tool providers discovered at runtime, their `ui/confirm` prompts bridged into the protocol's confirmation frames for HITL. Gated: an extension contributes tools **only** if you name it in `SMOOTH_EXTENSIONS_ALLOW`. Nothing loads by default.
+
+**Now declare the lines it can't cross.** Install an `AgentConfigResolver`, and every tool — built-in, yours, or from an extension — flows through the same gates:
+
+- **Per-agent allow-list** — an agent's `tool_config.enabledTools` restricts its turn to exactly those tools. Off the list, off the table.
+- **The authLevel gate** — a tool declaring `supports_auth_requirement = True` is *blocked at call time* on a public agent when tagged `admin`, or when tagged `end_user` and the session isn't identity-verified (its OTP bit, or your `SessionAuthenticator` seam). **Fail-closed** — an absent authenticator means "not authenticated".
+- **End-user OTP flow** — a refused `end_user` tool can offer a one-time-code identity flow via the `OtpService` seam; the server never generates, delivers, or validates a code (the host owns generation, delivery, expiry, attempt counting).
+
+You decide what the agent can touch; the runner enforces it.
+
+---
+
+## What it does
+
+| Piece | Module | Mirrors |
+| --- | --- | --- |
+| WS transport + per-connection loop + single writer | `server.py` | Rust `server.rs`, C# `SmoothOperatorWebSocketExtensions` |
+| Frame dispatch (`ping` / `create` / `get` / `send_message`) | `dispatcher.py` | C# `FrameDispatcher`, Rust `handler.rs` |
+| Session + message store | `session_store.py` | C# `SessionStore`, Rust storage adapter |
+| Streaming turn (engine → protocol events) | `turn_runner.py` | C# `TurnRunner`, Rust `runner.rs` |
+| Per-agent config (instructions / workflow / persona / tools) | `agent_config.py` | monorepo `agents` schema |
+| Conversation-workflow steps + post-turn judge | `workflow.py` | monorepo `general-agent/workflow.ts` |
+| SEP extension hosting | `extensions.py` | Rust `extensions.rs` |
+| Auth verifier seam (permissive + local HS256 JWT) | `auth.py` | C# `Auth.cs`, Rust verifier seam |
+
+**Graceful SIGTERM drain.** A shared `asyncio.Event` cancel switch is the single source of truth for "stop". Each connection loop races "cancel set" vs "next inbound frame" — with the turn dispatch awaited *inside* the frame branch, so an in-flight turn finishes before the loop exits, then a backplane `detach` always runs.
+
+**Per-agent config + conversation workflows.** `create_conversation_session` carries only an agent UUID, so config is resolved server-side per turn: an agent's `instructions` become its system prompt; `personality` / `greeting` are appended (greeting only on the first turn); a `conversation_workflow` (goal + ordered steps) renders the current step into the prompt and a cheap post-turn judge advances the pointer when the criteria are met. Parsing is tolerant (malformed → server default, never crashes a session) and the judge is failure-tolerant (any error → stay on the current step). With no resolver installed, behavior is unchanged.
+
+---
+
+## Five languages, one protocol
+
+The *same* server — same wire protocol, same conformance corpus — exists in five languages. Run it where your stack already lives.
+
+| Language | Server package | Registry |
+| --- | --- | --- |
+| **Python** | `smooai-smooth-operator-server` | in-repo (this package) |
+| **Rust** | `smooai-smooth-operator-server` | [crates.io](https://crates.io/crates/smooai-smooth-operator-server) |
+| **C# / .NET** | `SmooAI.SmoothOperator.Server` | [in-repo](../../dotnet/server) |
+| **TypeScript** | `@smooai/smooth-operator-server` | [in-repo](../../typescript/server) |
+| **Go** | `github.com/SmooAI/smooth-operator/go/server` | [in-repo](../../go/server) |
+
+Every native client — [TypeScript](https://www.npmjs.com/package/@smooai/smooth-operator), Go, .NET, Python, Rust — connects to any of them unmodified.
+
+---
+
+## Develop
+
+```bash
+cd python/server
+uv sync
+uv run --quiet ruff format .
+uv run --quiet ruff check .
+uv run --quiet pytest -q
+```
+
+---
+
+Part of the **[smooth-operator](https://github.com/SmooAI/smooth-operator)** service — Smoo AI's polyglot AI agent service. Don't want to run it yourself? **[lom.smoo.ai](https://lom.smoo.ai)** hosts it for you.
+
+## License
+
+MIT © 2026 Smoo AI. See [LICENSE](https://github.com/SmooAI/smooth-operator/blob/main/LICENSE).

smooai_smooth_operator_server-1.23.1/README.md

@@ -0,0 +1,134 @@
+# smooai-smooth-operator-server
+
+<p>
+  <a href="https://smoo.ai"><img src="https://img.shields.io/badge/Smoo_AI-platform-00A6A6?style=for-the-badge&labelColor=020618" alt="Smoo AI"></a>
+  <a href="https://github.com/SmooAI/smooth-operator/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-FF6B6C?style=for-the-badge&labelColor=020618" alt="license"></a>
+  <a href="https://www.python.org"><img src="https://img.shields.io/badge/Python-%E2%89%A53.11-00A6A6?style=for-the-badge&labelColor=020618" alt="Python ≥ 3.11"></a>
+</p>
+
+**Wiring a chat loop is a weekend project. A production agent _server_ is not.**
+
+Sessions that survive a reconnect. A wire protocol your clients can actually speak. Streaming turns you can watch token by token. Tools the model can call — and hard limits on the ones it must never call. Human-in-the-loop when a tool wants to write.
+
+`smooai-smooth-operator-server` is that server, async and native to Python. It speaks the [smooth-operator](https://github.com/SmooAI/smooth-operator) wire protocol ([`spec/`](https://github.com/SmooAI/smooth-operator/tree/main/spec)) and consumes the in-process [`smooai-smooth-operator-core`](https://pypi.org/project/smooai-smooth-operator-core/) engine — each turn runs a `SmoothAgent` and maps its stream onto `stream_token` / `stream_chunk` / `eventual_response`. It's the Python sibling of the [Rust](../../rust/smooth-operator-server), [Go](../../go/server), [TypeScript](../../typescript/server), and [C#](../../dotnet/server) servers, all speaking the one protocol.
+
+> The client lives in [`python/src`](../src) (`smooai-smooth-operator`). This is the **server** half.
+
+---
+
+## Spin up a real agent server
+
+```bash
+python -m smooth_operator_server
+# → smooth-operator-server (local flavor, python) listening on ws://127.0.0.1:8787/ws
+```
+
+That's a full agent backend — sessions, streaming turns, tool-calling, citations — on one WebSocket, in-memory, auth off, zero config. Env knobs: `SMOOTH_OPERATOR_BIND` (default `127.0.0.1:8787`), `SMOOTH_OPERATOR_SEED_KB=1` for the demo knowledge docs. The gateway is read from `SMOOAI_GATEWAY_URL` / `SMOOAI_GATEWAY_KEY` — with no key, `send_message` returns a clean `LLM_UNAVAILABLE` error and the rest of the protocol still works.
+
+Or embed it in your own async app:
+
+```python
+import asyncio
+from smooth_operator_server import ServerState, serve
+from smooth_operator_server.session_store import InMemorySessionStore
+
+async def main():
+    state = ServerState(store=InMemorySessionStore(), chat_client=my_openai_client)
+    server = await serve(state, "127.0.0.1", 0)  # port 0 → ephemeral
+    print(server.ws_url())
+    # ... drive real streaming turns ...
+    await server.shutdown()  # graceful drain + clean exit
+
+asyncio.run(main())
+```
+
+---
+
+## Extensible — and safe by construction
+
+An agent is only useful when it can *do* things, and only trustworthy when you can say what it may never do. This server gives you both seams.
+
+**Give it your tools.** Hand engine `Tool`s to `ServerState` and they merge with the built-ins for every turn:
+
+```python
+from smooth_operator_core import Tool  # the engine's tool base
+
+class OpenTicket(Tool):
+    name = "open_ticket"
+    description = "Open a support ticket for the current customer."
+    parameters = {"type": "object", "properties": {"subject": {"type": "string"}}}
+
+    async def execute(self, arguments):
+        return f"ticket opened: {arguments}"
+
+state = ServerState(
+    store=InMemorySessionStore(),
+    chat_client=my_client,
+    tools=[OpenTicket()],
+)
+```
+
+**Or let it gain tools with no redeploy.** The server hosts [SEP extensions](https://github.com/SmooAI/smooth-operator/blob/main/docs/TOOLS.md) — out-of-process tool providers discovered at runtime, their `ui/confirm` prompts bridged into the protocol's confirmation frames for HITL. Gated: an extension contributes tools **only** if you name it in `SMOOTH_EXTENSIONS_ALLOW`. Nothing loads by default.
+
+**Now declare the lines it can't cross.** Install an `AgentConfigResolver`, and every tool — built-in, yours, or from an extension — flows through the same gates:
+
+- **Per-agent allow-list** — an agent's `tool_config.enabledTools` restricts its turn to exactly those tools. Off the list, off the table.
+- **The authLevel gate** — a tool declaring `supports_auth_requirement = True` is *blocked at call time* on a public agent when tagged `admin`, or when tagged `end_user` and the session isn't identity-verified (its OTP bit, or your `SessionAuthenticator` seam). **Fail-closed** — an absent authenticator means "not authenticated".
+- **End-user OTP flow** — a refused `end_user` tool can offer a one-time-code identity flow via the `OtpService` seam; the server never generates, delivers, or validates a code (the host owns generation, delivery, expiry, attempt counting).
+
+You decide what the agent can touch; the runner enforces it.
+
+---
+
+## What it does
+
+| Piece | Module | Mirrors |
+| --- | --- | --- |
+| WS transport + per-connection loop + single writer | `server.py` | Rust `server.rs`, C# `SmoothOperatorWebSocketExtensions` |
+| Frame dispatch (`ping` / `create` / `get` / `send_message`) | `dispatcher.py` | C# `FrameDispatcher`, Rust `handler.rs` |
+| Session + message store | `session_store.py` | C# `SessionStore`, Rust storage adapter |
+| Streaming turn (engine → protocol events) | `turn_runner.py` | C# `TurnRunner`, Rust `runner.rs` |
+| Per-agent config (instructions / workflow / persona / tools) | `agent_config.py` | monorepo `agents` schema |
+| Conversation-workflow steps + post-turn judge | `workflow.py` | monorepo `general-agent/workflow.ts` |
+| SEP extension hosting | `extensions.py` | Rust `extensions.rs` |
+| Auth verifier seam (permissive + local HS256 JWT) | `auth.py` | C# `Auth.cs`, Rust verifier seam |
+
+**Graceful SIGTERM drain.** A shared `asyncio.Event` cancel switch is the single source of truth for "stop". Each connection loop races "cancel set" vs "next inbound frame" — with the turn dispatch awaited *inside* the frame branch, so an in-flight turn finishes before the loop exits, then a backplane `detach` always runs.
+
+**Per-agent config + conversation workflows.** `create_conversation_session` carries only an agent UUID, so config is resolved server-side per turn: an agent's `instructions` become its system prompt; `personality` / `greeting` are appended (greeting only on the first turn); a `conversation_workflow` (goal + ordered steps) renders the current step into the prompt and a cheap post-turn judge advances the pointer when the criteria are met. Parsing is tolerant (malformed → server default, never crashes a session) and the judge is failure-tolerant (any error → stay on the current step). With no resolver installed, behavior is unchanged.
+
+---
+
+## Five languages, one protocol
+
+The *same* server — same wire protocol, same conformance corpus — exists in five languages. Run it where your stack already lives.
+
+| Language | Server package | Registry |
+| --- | --- | --- |
+| **Python** | `smooai-smooth-operator-server` | in-repo (this package) |
+| **Rust** | `smooai-smooth-operator-server` | [crates.io](https://crates.io/crates/smooai-smooth-operator-server) |
+| **C# / .NET** | `SmooAI.SmoothOperator.Server` | [in-repo](../../dotnet/server) |
+| **TypeScript** | `@smooai/smooth-operator-server` | [in-repo](../../typescript/server) |
+| **Go** | `github.com/SmooAI/smooth-operator/go/server` | [in-repo](../../go/server) |
+
+Every native client — [TypeScript](https://www.npmjs.com/package/@smooai/smooth-operator), Go, .NET, Python, Rust — connects to any of them unmodified.
+
+---
+
+## Develop
+
+```bash
+cd python/server
+uv sync
+uv run --quiet ruff format .
+uv run --quiet ruff check .
+uv run --quiet pytest -q
+```
+
+---
+
+Part of the **[smooth-operator](https://github.com/SmooAI/smooth-operator)** service — Smoo AI's polyglot AI agent service. Don't want to run it yourself? **[lom.smoo.ai](https://lom.smoo.ai)** hosts it for you.
+
+## License
+
+MIT © 2026 Smoo AI. See [LICENSE](https://github.com/SmooAI/smooth-operator/blob/main/LICENSE).

smooai_smooth_operator_server-1.23.1/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "smooai-smooth-operator-server"
+version = "1.23.1"
+description = "Native async WebSocket server for the smooth-operator protocol — parity with the Rust and C# reference servers, consuming the in-process smooai-smooth-operator-core engine."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+dependencies = [
+    # The engine the server runs in-process per turn. `SmoothAgent.run_stream(...)`
+    # is mapped onto the protocol's stream_token / stream_chunk / eventual_response.
+    "smooai-smooth-operator-core>=1.3.2",
+    # asyncio WebSocket transport (server side).
+    "websockets>=12",
+]
+
+[project.optional-dependencies]
+# A live (non-mock) turn needs an OpenAI-compatible async client against the
+# SmooAI gateway. Optional: the server is fully testable on MockLlmProvider with
+# no gateway, and protocol-only paths (create/get/ping) need no LLM at all.
+gateway = ["openai>=1.40"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.4",
+    # The turn round-trip test drives the engine on MockLlmProvider, which ships
+    # in smooai-smooth-operator-core — no gateway needed.
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/smooth_operator_server"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+extend-select = ["I"]

smooai_smooth_operator_server-1.23.1/src/smooth_operator_server/__init__.py

@@ -0,0 +1,87 @@
+"""Native async WebSocket server for the smooth-operator protocol.
+
+A parity implementation of the Rust (``rust/smooth-operator-server``) and C#
+(``dotnet/server``) reference servers, consuming the in-process
+``smooai-smooth-operator-core`` engine. The server runs a :class:`SmoothAgent` per
+turn and maps its stream events onto the wire protocol's ``stream_token`` /
+``stream_chunk`` / ``eventual_response`` events.
+
+Quick start (embeddable, in-memory, auth off)::
+
+    import asyncio
+    from smooth_operator_server import serve_local
+
+    asyncio.run(serve_local("127.0.0.1:8787", seed_kb=True))
+"""
+
+from __future__ import annotations
+
+from . import protocol
+from .auth import (
+    AccessContext,
+    AuthVerifier,
+    LocalTokenVerifier,
+    NoAuthVerifier,
+    Principal,
+)
+from .backplane import Backplane, InMemoryBackplane
+from .dispatcher import FrameDispatcher
+from .otp import (
+    OtpChannel,
+    OtpContact,
+    OtpDelivery,
+    OtpError,
+    OtpInvalid,
+    OtpService,
+    OtpVerified,
+    OtpVerifyOutcome,
+)
+from .server import (
+    DEFAULT_HOST,
+    DEFAULT_PORT,
+    Server,
+    ServerState,
+    serve,
+    serve_local,
+)
+from .session_store import (
+    InMemorySessionStore,
+    MessageDirection,
+    SessionStore,
+    StoredMessage,
+    StoredSession,
+)
+from .turn_runner import TurnResult, TurnRunner
+
+__all__ = [
+    "protocol",
+    "AccessContext",
+    "AuthVerifier",
+    "LocalTokenVerifier",
+    "NoAuthVerifier",
+    "Principal",
+    "Backplane",
+    "InMemoryBackplane",
+    "FrameDispatcher",
+    "OtpChannel",
+    "OtpContact",
+    "OtpDelivery",
+    "OtpError",
+    "OtpInvalid",
+    "OtpService",
+    "OtpVerified",
+    "OtpVerifyOutcome",
+    "DEFAULT_HOST",
+    "DEFAULT_PORT",
+    "Server",
+    "ServerState",
+    "serve",
+    "serve_local",
+    "InMemorySessionStore",
+    "MessageDirection",
+    "SessionStore",
+    "StoredMessage",
+    "StoredSession",
+    "TurnResult",
+    "TurnRunner",
+]

smooai_smooth_operator_server-1.23.1/src/smooth_operator_server/__main__.py

@@ -0,0 +1,27 @@
+"""Run the local-flavor server: ``python -m smooth_operator_server``.
+
+Boots a fully in-memory, auth-off server on ``SMOOTH_OPERATOR_BIND`` (default
+``127.0.0.1:8787``) and serves until killed. ``SMOOTH_OPERATOR_SEED_KB=1`` loads the
+demo knowledge docs. The LLM gateway is read from ``SMOOAI_GATEWAY_URL`` /
+``SMOOAI_GATEWAY_KEY``; absent, ``send_message`` errors cleanly.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+from .server import DEFAULT_HOST, DEFAULT_PORT, serve_local
+
+
+def main() -> None:
+    addr = os.environ.get("SMOOTH_OPERATOR_BIND", f"{DEFAULT_HOST}:{DEFAULT_PORT}")
+    seed_kb = os.environ.get("SMOOTH_OPERATOR_SEED_KB", "") not in ("", "0", "false", "False")
+    try:
+        asyncio.run(serve_local(addr, seed_kb=seed_kb))
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    main()