Metadata-Version: 2.4
Name: conduit-ai-agents
Version: 0.1.0
Summary: Cross-framework AI agent observability and reliability shim
License: MIT License
        
        Copyright (c) 2026 Conduit
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agents,ai,langgraph,observability,opentelemetry
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: fastapi>=0.111.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: jsonschema>=4.22.0
Requires-Dist: opentelemetry-api>=1.25.0
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.25.0
Requires-Dist: opentelemetry-sdk>=1.25.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Requires-Dist: uvicorn>=0.30.0
Provides-Extra: crewai
Requires-Dist: crewai>=0.80.0; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.2.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: langgraph
Requires-Dist: langgraph>=1.0.0; extra == 'langgraph'
Requires-Dist: langsmith>=0.1.0; extra == 'langgraph'
Provides-Extra: openai
Requires-Dist: openai-agents>=0.0.14; extra == 'openai'
Description-Content-Type: text/markdown

# Conduit

> "LangSmith tells you what your agent did. Conduit tells you what went wrong, why, and fixes it — across any framework you already use."

Conduit is a cross-framework AI agent observability and reliability shim. It intercepts tool calls via OpenTelemetry, validates schemas, detects loops, and injects recovery context — all in < 5ms, without modifying your agent code.

## Quick Start (< 5 minutes)

```bash
pip install conduit
```

### LangGraph (2 lines)

```python
from conduit.shim.adapters.langgraph import install_for_langgraph
install_for_langgraph()

# Your existing LangGraph code — unchanged
graph = StateGraph(State)
# ...
```

### OpenAI Agents SDK (2 lines)

```python
from conduit.shim.adapters.openai_sdk import install_for_openai_sdk
install_for_openai_sdk()

# Your existing agent code — unchanged
agent = Agent(name="...", tools=[...])
```

### Start the dashboard

```bash
conduit dashboard
# → http://127.0.0.1:7432
```

## What Conduit Does

| Problem | Conduit's solution |
|---------|-------------------|
| Tool called with wrong param types | Schema validator auto-corrects `"10"` → `10` before execution |
| Agent loops on the same failed call | Loop detector fires at N=3, injects replan context |
| Tool times out repeatedly | Failure classifier + recovery engine retries with backoff |
| Schema drifted since agent was written | Drift detection + `conduit schema update` to fix |
| No visibility into agent failures | Dashboard with live failure feed + prescriptive recommendations |

## CLI

```bash
conduit dashboard                          # Start web dashboard
conduit stream                             # Live failure stream in terminal
conduit recommend                          # Print current recommendations

conduit schema list                        # List registered schemas
conduit schema validate search_web \
  --params '{"query":"test","max_results":"10"}'   # Validate params
conduit schema update search_web --from-drift      # Accept observed drift
conduit schema discover email_send                 # Infer schema from call history
conduit fix --recommendation UPDATE_SCHEMA_search_web
```

## Register a Schema

```python
from conduit.registry.store import SchemaRegistry

registry = SchemaRegistry("./conduit.db")
registry.register(
    tool_id="search_web",
    schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
            "max_results": {"type": "integer", "minimum": 1, "maximum": 100},
        },
        "required": ["query", "max_results"],
    },
    version="1.0.0",
)
```

## Ingest MCP Manifests

```python
from conduit.registry.mcp import ingest_mcp_manifest, discover_mcp_servers

# From a file
ingest_mcp_manifest(registry, "/path/to/mcp_server.json")

# Auto-discover from CLAUDE_MCP_SERVERS env var
discover_mcp_servers(registry)
```

## Configuration (`conduit.yaml`)

```yaml
shim:
  timeout_ms: 5          # Pass-through if intelligence plane takes > 5ms
  fallback: pass_through

validation:
  hard_gate: false       # true = block invalid calls; false = log and pass
  auto_correct: true     # Auto-fix type mismatches, field renames

detection:
  loop_threshold: 3      # N identical calls = loop detected
  loop_window: 10

recovery:
  enabled: true
  max_retries: 2

registry:
  db_path: ./conduit.db
```

## Key Invariants

1. **Never raises into agent code** — all hooks are `try/except`
2. **Never blocks** — passes through if intelligence plane exceeds `timeout_ms`
3. **Privacy by default** — no param values logged without `CONDUIT_LOG_PAYLOADS=true`
4. **Loop detector is per-task** — parallel agents never interfere
5. **Recovery is idempotent** — same failure never injected twice

## Architecture

```
Agent (LangGraph / OpenAI SDK / CrewAI)
    │
    ▼ tool calls
[Conduit ConduitProcessor]  ← OTel SpanProcessor
    │ pre-hook: SchemaValidator (< 3ms)
    │ post-hook: ToolFailureDetector + AgentLoopDetector + RecoveryEngine
    ▼
OTel Collector → SQLite (conduit.db)
    ▼
Dashboard (localhost:7432) — prescriptive recommendations
```

## REST API

```
GET  /api/v1/health
GET  /api/v1/failures
GET  /api/v1/failures/{event_id}
GET  /api/v1/failures/stream          # SSE
GET  /api/v1/recommendations
GET  /api/v1/tools
GET  /api/v1/tools/{tool_id}
GET  /api/v1/schemas
GET  /api/v1/schemas/{tool_id}
POST /api/v1/schemas/{tool_id}/accept_drift
GET  /api/v1/analytics/failure_rate
GET  /api/v1/analytics/recovery_rate
```

## License

MIT — core shim, adapters, schema validator, loop detector.
