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.
- agentspec_sdk-0.5.0/.gitignore +70 -0
- agentspec_sdk-0.5.0/PKG-INFO +75 -0
- agentspec_sdk-0.5.0/README.md +59 -0
- agentspec_sdk-0.5.0/agentspec_sdk/__init__.py +19 -0
- agentspec_sdk-0.5.0/agentspec_sdk/agentspec_contract.py +522 -0
- agentspec_sdk-0.5.0/agentspec_sdk/evidence_points.py +385 -0
- agentspec_sdk-0.5.0/agentspec_sdk/manifest.py +36 -0
- agentspec_sdk-0.5.0/agentspec_sdk/manifest_hash.py +52 -0
- agentspec_sdk-0.5.0/agentspec_sdk/memory_points.py +359 -0
- agentspec_sdk-0.5.0/agentspec_sdk/reporter.py +319 -0
- agentspec_sdk-0.5.0/agentspec_sdk/types.py +33 -0
- agentspec_sdk-0.5.0/pyproject.toml +27 -0
- agentspec_sdk-0.5.0/tests/__init__.py +0 -0
- agentspec_sdk-0.5.0/tests/conftest.py +28 -0
- agentspec_sdk-0.5.0/tests/test_evidence_contract.py +63 -0
- agentspec_sdk-0.5.0/tests/test_evidence_points.py +365 -0
- agentspec_sdk-0.5.0/tests/test_evidence_points_memory.py +420 -0
- agentspec_sdk-0.5.0/tests/test_evidence_points_tool_mcp_logging.py +275 -0
- agentspec_sdk-0.5.0/tests/test_package_name.py +21 -0
- agentspec_sdk-0.5.0/tests/test_push_evidence_inflight.py +173 -0
- agentspec_sdk-0.5.0/tests/test_push_mode.py +357 -0
- agentspec_sdk-0.5.0/tests/test_reporter.py +158 -0
- agentspec_sdk-0.5.0/tests/test_reporter_report.py +52 -0
- agentspec_sdk-0.5.0/tests/test_scrub_behaviour.py +48 -0
|
@@ -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"]
|