sectr 0.0.4__tar.gz

sectr-0.0.4/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.3
+Name: sectr
+Version: 0.0.4
+Summary: Sectr Python SDK: framework-agnostic agent deployment (decorators + runner-contract adapter)
+Author: Donald Pinckney
+Author-email: Donald Pinckney <donald_pinckney@icloud.com>
+Requires-Dist: fastapi
+Requires-Dist: uvicorn
+Requires-Dist: claude-code-sdk ; extra == 'claude-code'
+Requires-Dist: fastmcp ; extra == 'claude-code'
+Requires-Dist: langgraph ; extra == 'langgraph'
+Requires-Dist: openai-agents>=0.2,<1 ; extra == 'openai-agents'
+Requires-Python: >=3.12
+Provides-Extra: claude-code
+Provides-Extra: langgraph
+Provides-Extra: openai-agents
+Description-Content-Type: text/markdown
+

sectr-0.0.4/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "sectr"
+version = "0.0.4"
+description = "Sectr Python SDK: framework-agnostic agent deployment (decorators + runner-contract adapter)"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi",
+    "uvicorn",
+]
+
+[[project.authors]]
+name = "Donald Pinckney"
+email = "donald_pinckney@icloud.com"
+
+[project.optional-dependencies]
+openai-agents = ["openai-agents>=0.2,<1"]
+langgraph = ["langgraph"]
+claude-code = [
+    "claude-code-sdk",
+    "fastmcp",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "httpx>=0.27",
+    "pytest-asyncio>=0.24",
+    "jsonschema>=4.23",
+    "rfc3339-validator>=0.1.4",
+    "mypy>=2.3.1",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"

sectr-0.0.4/pyproject.toml.orig

@@ -0,0 +1,40 @@
+[project]
+name = "sectr"
+version = "0.0.4"
+description = "Sectr Python SDK: framework-agnostic agent deployment (decorators + runner-contract adapter)"
+readme = "README.md"
+authors = [
+    { name = "Donald Pinckney", email = "donald_pinckney@icloud.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    # The FastAPI runner-contract adapter (sectr.server) — base dep (decided
+    # 2026-09-10): every HOSTED variant needs it, so it belongs to the SDK's
+    # core; the extras exist only for framework imports the core doesn't
+    # require.
+    "fastapi",
+    "uvicorn",
+]
+
+[project.optional-dependencies]
+# Framework adapters (each extra mirrors an examples/ variant).
+openai-agents = ["openai-agents>=0.2,<1"]
+langgraph = ["langgraph"]
+claude-code = ["claude-code-sdk", "fastmcp"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "httpx>=0.27",
+    "pytest-asyncio>=0.24",
+    "jsonschema>=4.23",
+    "rfc3339-validator>=0.1.4",
+    "mypy>=2.3.1",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"

sectr-0.0.4/src/sectr/__init__.py

@@ -0,0 +1,53 @@
+"""Sectr Python SDK: framework-agnostic agent deployment.
+
+Core (framework-free): `AgentApp` (route registry), `SessionContext` (the
+handler argument), `sectr.events` (typed events mirroring
+schema/event.schema.json), `sectr.tools` (`@tool` registry + approval
+gating). Handlers are async generators of events; the FastAPI server
+adapter (`sectr.server`) speaks the runner invoke contract, and framework
+adapters (`sectr.adapters.*`) wrap native framework objects into handlers.
+
+Contracts: `../schema/` is the single source of truth — see `schema/PLAN.md`
+and `sdk-python/PLAN.md`.
+"""
+
+from .app import AgentApp, Handler, Route
+from .context import SessionContext
+from .events import (
+    Envelope,
+    Error,
+    MessageDelta,
+    MessageEnd,
+    MessageStart,
+    NoMoreActions,
+    RunnerEvent,
+    TranscriptCompacted,
+    ToolApprovalRequired,
+    ToolCall,
+    ToolResult,
+    NoMoreActions,
+)
+from .tools import ApprovalRequired, Tool, tool
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AgentApp",
+    "ApprovalRequired",
+    "Envelope",
+    "Error",
+    "Handler",
+    "MessageDelta",
+    "MessageEnd",
+    "MessageStart",
+    "Route",
+    "RunnerEvent",
+    "SessionContext",
+    "Tool",
+    "ToolApprovalRequired",
+    "ToolCall",
+    "ToolResult",
+    "NoMoreActions",
+    "TranscriptCompacted",
+    "tool",
+]

sectr-0.0.4/src/sectr/adapters/__init__.py

@@ -0,0 +1,12 @@
+"""Framework adapters (optional extras). Each adapter is a handler factory:
+it takes the framework's native object and returns a
+`(SessionContext) -> AsyncIterator[RunnerEvent]` handler, so registration is
+one line per app:
+
+    app.add_route("/chat", openai_agents(agent))
+    app.add_route("/chat", langgraph(graph))
+    app.add_route("/chat", claude_code(options))
+
+Mapping details (pause/resume semantics, transcript reconstruction) are
+documented per module and pinned by the variant sketches in `examples/`.
+"""

sectr-0.0.4/src/sectr/adapters/claude_code.py

@@ -0,0 +1,45 @@
+"""Claude Code adapter (`sectr[claude-code]` extra) — the near-black-box
+case: the CLI owns its loop, tools, and permissions.
+
+`claude_code(**options)` returns a handler that (see
+`examples/claude-code/main.py`; session-memory mapping decided in
+`examples/claude-code/PLAN.md`):
+
+- runs the `claude` CLI (via claude-code-sdk) with `--resume` keyed to our
+  session_id (option (b): the CLI's workspace state persists across turns;
+  the journal stays authoritative for approvals, SSE, audit, transcript);
+- assistant text → MESSAGE_*; ToolUseBlock → TOOL_CALL; ToolResultBlock →
+  TOOL_RESULT; result message → NO_MORE_ACTIONS (turn over);
+- pause: the CLI's `can_use_tool` permission callback fires → the adapter
+  captures (tool_name, input), terminates the subprocess, journals
+  TOOL_APPROVAL_REQUIRED as the final frame (turn suspended, no sentinel);
+- resume: `--resume` the same session; when the CLI re-issues the gated
+  tool and asks permission, the adapter answers from
+  `ctx.decision` (allow/deny). At most ONE pending approval per
+  session is possible by the turn model.
+
+CI note: the `claude` binary is a shim script emitting canned JSONL
+(examples/claude-code/tests/shim_claude.py). Implementation pending.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Any
+
+from ..app import Handler
+from ..context import SessionContext
+from ..events import RunnerEvent
+
+__all__ = ["claude_code"]
+
+
+def claude_code(**options: Any) -> Handler:
+    """Handler factory wrapping claude-code-sdk options. Implementation
+    pending."""
+
+    async def handler(ctx: SessionContext) -> AsyncIterator[RunnerEvent]:
+        raise NotImplementedError("sectr.adapters.claude_code")
+        yield  # pragma: no cover - makes this an async generator
+
+    return handler

sectr-0.0.4/src/sectr/adapters/langgraph.py

@@ -0,0 +1,80 @@
+"""LangGraph adapter (`sectr[langgraph]` extra).
+
+`langgraph(graph)` returns a handler that (see `examples/langgraph/main.py`):
+
+- normal turn: transcript → `{"messages": [...]}` state; `graph.astream`
+  (stream_mode="messages") → MESSAGE_* / TOOL_CALL / TOOL_RESULT;
+  stream end → NO_MORE_ACTIONS (turn over). No LangGraph checkpointer — the journal
+  is the checkpoint.
+- pause: the sectr-gated tool raises `ApprovalRequired` inside the tool
+  node; the adapter catches it escaping `astream` → journaled
+  TOOL_APPROVAL_REQUIRED as the final frame (turn suspended, no sentinel).
+- resume: rebuild messages from the transcript, execute the approved tool
+  via the sectr tool wrapper (or denial), append the ToolMessage, continue.
+
+Post-MVP option (recorded in sdk-python/PLAN.md): a session-scoped
+checkpointer workspace enables idiomatic `interrupt()` /
+`Command(resume=decision)` tool bodies. Implementation pending.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Any, cast
+
+from ..app import Handler
+from ..context import SessionContext
+from ..events import RunnerEvent
+from ..tools import ApprovalRequired
+
+__all__ = ["langgraph", "as_langgraph_tool"]
+
+
+def langgraph(graph: Any) -> Handler:
+    """Handler factory wrapping a compiled LangGraph. Implementation pending."""
+
+    async def handler(ctx: SessionContext) -> AsyncIterator[RunnerEvent]:
+        raise NotImplementedError("sectr.adapters.langgraph")
+        yield  # pragma: no cover - makes this an async generator
+
+    return handler
+
+
+def as_langgraph_tool(t: Any) -> Any:
+    """Convert a sectr `Tool` into a LangGraph/langchain-compatible tool,
+    preserving approval gating: the coroutine raises `ApprovalRequired`
+    inside the tool node when gated (the adapter catches it escaping
+    `astream` and ends the turn). Skeleton implementation — schema inferred
+    from the original function signature; golden tests arrive with the
+    adapter's functional round."""
+    import inspect
+
+    from langchain_core.tools import StructuredTool
+    from pydantic import create_model
+
+    if t.description is None:
+        raise ValueError(f"tool {t.name!r} needs a docstring (used as the LLM description)")
+
+    params = inspect.signature(t.fn).parameters
+    fields = {
+        pname: (
+            p.annotation if p.annotation is not inspect.Parameter.empty else str,
+            ... if p.default is inspect.Parameter.empty else p.default,
+        )
+        for pname, p in params.items()
+    }
+    # pydantic's create_model overloads don't cleanly accept a heterogeneous
+    # kwargs dict — a cast is honest here; schema correctness is golden-tested
+    # with the adapter's functional round.
+    args_schema = create_model(f"{t.name}_args", **cast(Any, fields))
+
+    from ..tools import is_gated
+
+    async def _run(**kwargs: Any) -> Any:
+        if is_gated(t.name):
+            raise ApprovalRequired(t.name, kwargs)
+        return await t(**kwargs)
+
+    return StructuredTool.from_function(
+        coroutine=_run, name=t.name, description=t.description, args_schema=args_schema
+    )