Metadata-Version: 2.4
Name: testneo-agent-sdk
Version: 0.1.0
Summary: TestNeo Agent SDK — emit agent_run_summary.v1 and ingest into TestNeo (framework adapters optional).
Author: TestNeo
License: MIT
Project-URL: Homepage, https://app.testneo.ai
Project-URL: Documentation, https://github.com/gururajhm-neo/testneo-api/tree/main/packages/testneo-agent-sdk
Keywords: testneo,agent,verification,langgraph,crewai,autogen
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.6
Provides-Extra: langgraph
Requires-Dist: langchain-core>=0.2; extra == "langgraph"
Provides-Extra: crewai
Provides-Extra: autogen
Provides-Extra: openai
Provides-Extra: all
Requires-Dist: langchain-core>=0.2; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"

# TestNeo Agent SDK

Official Python SDK to **emit** `agent_run_summary.v1` and **ingest** into TestNeo.

Verification (PASS / WARN / BLOCK) stays on the server. This package never implements the gate.

```text
Your agent / framework
      → TestNeo SDK (or thin adapter)
      → agent_run_summary.v1
      → POST ingest
      → TestNeo Verify / Eval
```

## Install

```bash
pip install -e "packages/testneo-agent-sdk[dev]"
# optional extras later: [langgraph]
```

## 10-minute generic path

```bash
export TESTNEO_BASE_URL=http://127.0.0.1:8001
export TESTNEO_API_KEY=...
export TESTNEO_PROJECT_ID=15
```

```python
from testneo_agent import TestNeo, refund_policy_v2

sdk = TestNeo.from_env()

with sdk.run(goal="Refund order 430") as run:
    run.authorization("READ_WRITE")
    cid = run.tool_called("search_policy_kb", operation="READ", target="policy_refund_v2")
    run.retrieval(
        doc_id="policy_refund_v2",
        snippet="Full refunds only within 30 days of purchase.",
        score=0.88,
        emit_action=False,
    )
    run.tool_completed(call_id=cid, result_summary="matched policy_refund_v2")
    run.confirmation(True)
    run.set_gate_contract(refund_policy_v2(order_id=430))
    run.set_claim("Full refund within 30 days per policy v2.")
# __exit__ builds summary + ingests (TESTNEO_AUTO_INGEST=true by default)
```

Then open **Agent Verification → Verify** and select the ingested run.

## Framework adapters (P0)

Thin translators only — no HTTP, no gate logic.

| Adapter | Import |
|---------|--------|
| Generic | `from testneo_agent.adapters import GenericAdapter` |
| LangGraph / LangChain | `from testneo_agent.adapters import LangGraphAdapter` |
| CrewAI | `from testneo_agent.adapters import CrewAIAdapter` |
| AutoGen / AG2 | `from testneo_agent.adapters import AutoGenAdapter` |

```python
from testneo_agent import TestNeo
from testneo_agent.adapters import LangGraphAdapter

sdk = TestNeo.from_env()
with sdk.run(goal="...", source="langgraph", auto_ingest=True) as run:
    adapter = LangGraphAdapter()
    adapter.bind(run)
    for ev in graph_stream_events:  # your native events
        adapter.on_native_event(ev)
    adapter.finish(final_message)
```

## Architecture

See [docs/architecture/TESTNEO_AGENT_SDK_ADAPTERS_PLAN.md](../../docs/architecture/TESTNEO_AGENT_SDK_ADAPTERS_PLAN.md).

| Layer | Responsibility |
|-------|----------------|
| `TestNeoRun` | Public instrumentation API |
| Adapters | Native events → internal events |
| Aggregator | Internal events → `agent_run_summary.v1` |
| Client | Ingest (+ optional post-agent-gate) |

## Config

| Env | Purpose |
|-----|---------|
| `TESTNEO_BASE_URL` | API host (e.g. `http://127.0.0.1:8001`) |
| `TESTNEO_API_KEY` | Bearer token |
| `TESTNEO_PROJECT_ID` | Project id |
| `TESTNEO_AUTO_INGEST` | default `true` |
| `TESTNEO_AUTO_VERIFY` | default `false` (ingest ≠ gate) |
| `TESTNEO_SDK_STRICT` | raise on SDK errors |
| `TESTNEO_SDK_DEBUG` | debug logs (secrets masked) |

## Tests

```bash
cd packages/testneo-agent-sdk
pip install -e ".[dev]"
pytest -q
```

## Non-goals

- Do not modify the verification engine from this package
- Do not hand-build `agent_run_summary.v1` in the happy path
- Adapters must not import the HTTP client
