agentspec-sdk 0.5.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,70 @@
1
+ # ── Dependencies ──────────────────────────────────────────────────────────────
2
+ node_modules/
3
+ .pnpm-store/
4
+
5
+ # ── Build output ──────────────────────────────────────────────────────────────
6
+ dist/
7
+ dist-cjs/
8
+ dist-esm/
9
+ *.tsbuildinfo
10
+
11
+ # ── VitePress ─────────────────────────────────────────────────────────────────
12
+ docs/.vitepress/dist/
13
+ docs/.vitepress/cache/
14
+
15
+ # ── Environment & secrets ─────────────────────────────────────────────────────
16
+ .env
17
+ .env.local
18
+ .env.*.local
19
+ *.env
20
+
21
+ # ── OS ────────────────────────────────────────────────────────────────────────
22
+ .DS_Store
23
+ Thumbs.db
24
+
25
+ # ── Editor ────────────────────────────────────────────────────────────────────
26
+ .vscode/
27
+ .idea/
28
+ *.swp
29
+ *.swo
30
+ .omc/
31
+
32
+ # ── Test & coverage ───────────────────────────────────────────────────────────
33
+ coverage/
34
+ .nyc_output/
35
+ # crapper, dryer and mutator (ub-mode): metrics, coverage reports, mutation backups
36
+ /.metrics/
37
+ /target/
38
+
39
+ # ── Logs ──────────────────────────────────────────────────────────────────────
40
+ *.log
41
+ npm-debug.log*
42
+ pnpm-debug.log*
43
+
44
+ # ── Microsoft Office ──────────────────────────────────────────────────────────
45
+ *.pptx
46
+ *.xlsx
47
+ *.docx
48
+ ~$*
49
+
50
+ # ── Python (global) ───────────────────────────────────────────────────────────
51
+ __pycache__/
52
+ **/__pycache__/
53
+ **/*.pyc
54
+ **/*.pyo
55
+ .pytest_cache/
56
+ **/.pytest_cache/
57
+
58
+ # ── Python SDK ────────────────────────────────────────────────────────────────
59
+ packages/sdk-python/.venv/
60
+
61
+ # ── Operator (Python) ─────────────────────────────────────────────────────────
62
+
63
+ # ── Worktrees ─────────────────────────────────────────────────────────────────
64
+ .worktrees/
65
+
66
+ # ── Misc ──────────────────────────────────────────────────────────────────────
67
+ *.ots
68
+ commit.txt
69
+ .venv-mockllm/
70
+ .demo-rolled-at
@@ -0,0 +1,75 @@
1
+ Metadata-Version: 2.5
2
+ Name: agentspec-sdk
3
+ Version: 0.5.0
4
+ Summary: Universal Agent Manifest SDK for Python agents
5
+ Requires-Python: >=3.10
6
+ Requires-Dist: httpx>=0.28.1
7
+ Requires-Dist: pydantic>=2.14.1
8
+ Requires-Dist: pyyaml>=6.0.3
9
+ Provides-Extra: dev
10
+ Requires-Dist: langchain-core>=1.0.0; extra == 'dev'
11
+ Requires-Dist: langgraph-checkpoint>=4.0.0; extra == 'dev'
12
+ Requires-Dist: pytest-asyncio>=1.4.1; extra == 'dev'
13
+ Requires-Dist: pytest>=9.1.1; extra == 'dev'
14
+ Requires-Dist: respx>=0.23.1; extra == 'dev'
15
+ Description-Content-Type: text/markdown
16
+
17
+ # agentspec-sdk
18
+
19
+ Python runtime SDK for [AgentSpec](https://github.com/agents-oss/agentspec): serves `GET /agentspec/health` and pushes state to the control plane from an agent described by `agent.yaml`.
20
+
21
+ ```bash
22
+ pip install agentspec-sdk
23
+ ```
24
+
25
+ ```python
26
+ from agentspec_sdk import AgentSpecReporter
27
+
28
+ reporter = AgentSpecReporter.from_yaml("agent.yaml")
29
+
30
+ # WSGI app answering GET /agentspec/health with the TypeScript HealthReport keys
31
+ # (agentName, checks[].latencyMs), so the sidecar sees the SDK. Mount it in your framework.
32
+ app = reporter.wsgi_app()
33
+ ```
34
+
35
+ Mount the app so the full request path is `/agentspec/health`. At the root it answers that path directly. Under a
36
+ prefix, the dispatcher moves the prefix into `SCRIPT_NAME`; the app compares `SCRIPT_NAME + PATH_INFO`, so
37
+ mounting it at `/agentspec` (for example `DispatcherMiddleware(fallback, {"/agentspec": reporter.wsgi_app()})`)
38
+ serves `/agentspec/health` too.
39
+
40
+ ## Evidence points
41
+
42
+ The SDK is the Python runtime SDK of ADR-0038: framework-agnostic, the same evidence points and record shapes as `@agentspec/sdk/runtime` in TypeScript. Create the reporter first, then wrap the operations the rules are about:
43
+
44
+ ```python
45
+ import agentspec_sdk
46
+ from agentspec_sdk import AgentSpecReporter
47
+
48
+ reporter = AgentSpecReporter.from_yaml("agent.yaml")
49
+
50
+
51
+ @agentspec_sdk.guardrail("input") # SEC-LLM-01; "output" for SEC-LLM-02
52
+ def run_input_guardrails(text: str) -> str:
53
+ return text
54
+
55
+
56
+ @agentspec_sdk.tool("search-web") # TOOL-01
57
+ def search_web(query: str) -> list[str]:
58
+ return []
59
+
60
+
61
+ reporter.start_push_mode(api_key="<agent token>") # heartbeat with each evidence point's state and records
62
+ ```
63
+
64
+ | Helper | Contract name | Wraps |
65
+ |---|---|---|
66
+ | `guardrail("input" \| "output")` | `guardrail` | A guardrail function (decorator) or block (`with`) |
67
+ | `tool(name)` | `tool` | A local tool function |
68
+ | `mcp_client(session, server)` | `mcpClient` | A stdio MCP client session |
69
+ | `memory_write(backend)` | `memoryWrite` | A LangGraph checkpointer or Store: scrubs, applies the TTL, audits |
70
+ | `vector_store(client, namespace=None)` | `vectorStore` | A vector store client |
71
+ | `structured_logging(logger=None)` | `logging` | The logger's stream handlers: JSON lines |
72
+
73
+ Each applicable evidence point is reported `fired`, `wired` or `not_wired`; `not_wired` never passes. See the [runtime SDK concept page](../../docs/concepts/runtime-sdk.md) and the [evidence wiring guide](../../docs/guides/wire-evidence-points.md).
74
+
75
+ The distribution is `agentspec-sdk` and the import is `agentspec_sdk`. The PyPI name `agentspec` belongs to an unrelated project.
@@ -0,0 +1,59 @@
1
+ # agentspec-sdk
2
+
3
+ Python runtime SDK for [AgentSpec](https://github.com/agents-oss/agentspec): serves `GET /agentspec/health` and pushes state to the control plane from an agent described by `agent.yaml`.
4
+
5
+ ```bash
6
+ pip install agentspec-sdk
7
+ ```
8
+
9
+ ```python
10
+ from agentspec_sdk import AgentSpecReporter
11
+
12
+ reporter = AgentSpecReporter.from_yaml("agent.yaml")
13
+
14
+ # WSGI app answering GET /agentspec/health with the TypeScript HealthReport keys
15
+ # (agentName, checks[].latencyMs), so the sidecar sees the SDK. Mount it in your framework.
16
+ app = reporter.wsgi_app()
17
+ ```
18
+
19
+ Mount the app so the full request path is `/agentspec/health`. At the root it answers that path directly. Under a
20
+ prefix, the dispatcher moves the prefix into `SCRIPT_NAME`; the app compares `SCRIPT_NAME + PATH_INFO`, so
21
+ mounting it at `/agentspec` (for example `DispatcherMiddleware(fallback, {"/agentspec": reporter.wsgi_app()})`)
22
+ serves `/agentspec/health` too.
23
+
24
+ ## Evidence points
25
+
26
+ The SDK is the Python runtime SDK of ADR-0038: framework-agnostic, the same evidence points and record shapes as `@agentspec/sdk/runtime` in TypeScript. Create the reporter first, then wrap the operations the rules are about:
27
+
28
+ ```python
29
+ import agentspec_sdk
30
+ from agentspec_sdk import AgentSpecReporter
31
+
32
+ reporter = AgentSpecReporter.from_yaml("agent.yaml")
33
+
34
+
35
+ @agentspec_sdk.guardrail("input") # SEC-LLM-01; "output" for SEC-LLM-02
36
+ def run_input_guardrails(text: str) -> str:
37
+ return text
38
+
39
+
40
+ @agentspec_sdk.tool("search-web") # TOOL-01
41
+ def search_web(query: str) -> list[str]:
42
+ return []
43
+
44
+
45
+ reporter.start_push_mode(api_key="<agent token>") # heartbeat with each evidence point's state and records
46
+ ```
47
+
48
+ | Helper | Contract name | Wraps |
49
+ |---|---|---|
50
+ | `guardrail("input" \| "output")` | `guardrail` | A guardrail function (decorator) or block (`with`) |
51
+ | `tool(name)` | `tool` | A local tool function |
52
+ | `mcp_client(session, server)` | `mcpClient` | A stdio MCP client session |
53
+ | `memory_write(backend)` | `memoryWrite` | A LangGraph checkpointer or Store: scrubs, applies the TTL, audits |
54
+ | `vector_store(client, namespace=None)` | `vectorStore` | A vector store client |
55
+ | `structured_logging(logger=None)` | `logging` | The logger's stream handlers: JSON lines |
56
+
57
+ Each applicable evidence point is reported `fired`, `wired` or `not_wired`; `not_wired` never passes. See the [runtime SDK concept page](../../docs/concepts/runtime-sdk.md) and the [evidence wiring guide](../../docs/guides/wire-evidence-points.md).
58
+
59
+ The distribution is `agentspec-sdk` and the import is `agentspec_sdk`. The PyPI name `agentspec` belongs to an unrelated project.
@@ -0,0 +1,19 @@
1
+ """
2
+ agentspec_sdk — Python SDK for AgentSpec Universal Agent Manifests.
3
+
4
+ Usage:
5
+ from agentspec_sdk import AgentSpecReporter
6
+
7
+ reporter = AgentSpecReporter.from_yaml("agent.yaml")
8
+ reporter.start_push_mode(
9
+ control_plane_url="https://control-plane.agentspec.io",
10
+ api_key="<agent token from POST /api/v1/register>",
11
+ )
12
+ """
13
+
14
+ from .evidence_points import guardrail, mcp_client, structured_logging, tool
15
+ from .memory_points import memory_write, vector_store
16
+ from .reporter import AgentSpecReporter
17
+ from .types import HealthReport, HealthCheck
18
+
19
+ __all__ = ["AgentSpecReporter", "guardrail", "tool", "mcp_client", "structured_logging", "memory_write", "vector_store", "HealthReport", "HealthCheck"]