isa-agent-sdk 0.2.0__tar.gz

isa_agent_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: isa-agent-sdk
+Version: 0.2.0
+Summary: isA Agent SDK - Build AI agents with human-in-the-loop capabilities, MCP integration, and advanced features
+Author-email: isA Team <support@isa-agent.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/isa-agent/sdk
+Project-URL: Documentation, https://docs.isa-agent.com/sdk
+Project-URL: Repository, https://github.com/isa-agent/sdk
+Project-URL: Issues, https://github.com/isa-agent/sdk/issues
+Keywords: ai,agent,sdk,llm,claude,anthropic,human-in-the-loop,mcp,model-context-protocol,langchain,langgraph
+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 :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1.0.0,>=0.26.0
+Requires-Dist: pydantic<3.0.0,>=2.0.0
+Requires-Dist: pydantic-settings<3.0.0,>=2.0.0
+Requires-Dist: isa-common<0.5.0,>=0.3.0
+Requires-Dist: isa-mcp<1.1.0,>=1.0.0
+Requires-Dist: isa-model<0.7.0,>=0.5.0
+Requires-Dist: langchain-core<2.0.0,>=1.2.0
+Requires-Dist: langgraph<2.0.0,>=1.0.0
+Requires-Dist: langchain-anthropic<2.0.0,>=1.3.0
+Requires-Dist: langchain-openai<2.0.0,>=1.1.0
+Requires-Dist: anyio<5.0.0,>=4.0.0
+Requires-Dist: aiofiles<26.0.0,>=23.0.0
+Requires-Dist: aiohttp<4.0.0,>=3.9.0
+Requires-Dist: rich<15.0.0,>=13.0.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: python-dotenv<2.0.0,>=1.0.0
+Requires-Dist: psutil<7.0.0,>=5.9.0
+Requires-Dist: click<9.0,>=8.0
+Requires-Dist: PyJWT<3.0.0,>=2.8.0
+Provides-Extra: server
+Requires-Dist: fastapi<1.0.0,>=0.109.0; extra == "server"
+Requires-Dist: uvicorn<1.0.0,>=0.27.0; extra == "server"
+Requires-Dist: sse-starlette<4.0.0,>=1.6.5; extra == "server"
+Requires-Dist: python-multipart<1.0.0,>=0.0.6; extra == "server"
+Requires-Dist: prometheus_client<1.0.0,>=0.20.0; extra == "server"
+Provides-Extra: nats
+Requires-Dist: nats-py<3.0.0,>=2.6.0; extra == "nats"
+Provides-Extra: persistence
+Requires-Dist: sqlalchemy<3.0.0,>=2.0.0; extra == "persistence"
+Requires-Dist: aiosqlite<1.0.0,>=0.19.0; extra == "persistence"
+Provides-Extra: analytics
+Requires-Dist: pandas<3.0.0,>=2.0.0; extra == "analytics"
+Requires-Dist: pyarrow<20.0.0,>=14.0.0; extra == "analytics"
+Provides-Extra: voice
+Requires-Dist: sounddevice<1.0.0,>=0.4.6; extra == "voice"
+Requires-Dist: webrtcvad<3.0.0,>=2.0.10; extra == "voice"
+Provides-Extra: observability
+Requires-Dist: opentelemetry-api>=1.20.0; extra == "observability"
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "observability"
+Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == "observability"
+Provides-Extra: keychain
+Requires-Dist: keyring>=24.0.0; extra == "keychain"
+Provides-Extra: dev
+Requires-Dist: pytest<9.0.0,>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio<2.0.0,>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov<8.0.0,>=4.0.0; extra == "dev"
+Requires-Dist: fakeredis[lua]<3.0.0,>=2.21.0; extra == "dev"
+Requires-Dist: black<27.0.0,>=23.0.0; extra == "dev"
+Requires-Dist: ruff<1.0.0,>=0.1.0; extra == "dev"
+Requires-Dist: mypy<2.0.0,>=1.0.0; extra == "dev"
+Requires-Dist: pip-audit>=2.6.0; extra == "dev"
+Requires-Dist: cyclonedx-bom>=4.0.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: isa-agent-sdk[analytics,dev,keychain,nats,observability,persistence,server,voice]; extra == "all"
+
+# isA Agent SDK
+
+[![Tests](https://github.com/xenoISA/isA_Agent_SDK/actions/workflows/test.yml/badge.svg)](https://github.com/xenoISA/isA_Agent_SDK/actions/workflows/test.yml)
+[![Dependency Audit](https://github.com/xenoISA/isA_Agent_SDK/actions/workflows/dependency-audit.yml/badge.svg)](https://github.com/xenoISA/isA_Agent_SDK/actions/workflows/dependency-audit.yml)
+
+A complete AI Agent SDK for building intelligent agents with advanced features. Compatible with Claude Agent SDK patterns, with additional capabilities.
+
+## Features
+
+- **Claude Agent SDK Compatible** - Familiar API patterns
+- **Streaming Messages** - Real-time response streaming
+- **Built-in Tools** - Read, Write, Edit, Bash, WebSearch, etc.
+- **MCP Integration** - Model Context Protocol with offline fallback
+- **Human-in-the-Loop** - Durable execution with checkpoints
+- **Skills System** - Local-first skill loading with MCP fallback
+- **Project Config** - `.isa` directory for project-specific settings
+- **Event Triggers** - Proactive agent activation
+- **Multiple Execution Modes** - Reactive, Collaborative, Proactive
+- **A2A Ready** - Agent Card + JSON-RPC client/server adapters
+- **Multi-Agent Swarm** - Dynamic agent handoffs with `[HANDOFF:]` directives
+- **DAG Task Execution** - Dependency-ordered workflows with parallel wavefronts
+- **Production Resilience** - Circuit breakers, bulkhead isolation, error classification, recovery playbooks
+- **Observability** - OpenTelemetry tracing, structured error logging, Prometheus metrics
+- **Intent-Driven Routing** - SenseNode classifies intent for automatic model tier selection
+- **Graceful Degradation** - Nodes skip optional operations when services are degraded
+- **3,500+ Tests** - Comprehensive coverage including chaos tests
+
+## Installation
+
+```bash
+pip install isa-agent-sdk
+
+# With FastAPI server support
+pip install isa-agent-sdk[server]
+
+# With OpenTelemetry tracing
+pip install isa-agent-sdk[observability]
+```
+
+## Project Setup
+
+Initialize a `.isa` directory for project-specific configuration:
+
+```bash
+mkdir -p .isa/skills
+```
+
+```
+my-project/
+├── .isa/
+│   ├── config.json          # Project configuration
+│   ├── settings.local.json  # MCP servers, permissions
+│   └── skills/              # Local skills (loaded first)
+│       └── my-skill/
+│           └── SKILL.md
+└── ...
+```
+
+Skills in `.isa/skills/` are loaded before MCP, allowing project-specific overrides.
+
+## Quick Start
+
+### Basic Query
+
+```python
+from isa_agent_sdk import query, ISAAgentOptions
+
+# Simple usage
+async for msg in query("Hello, world!"):
+    print(msg.content)
+
+# With options
+async for msg in query(
+    "Fix the bug in auth.py",
+    options=ISAAgentOptions(
+        allowed_tools=["Read", "Edit", "Bash"],
+        execution_mode="collaborative"
+    )
+):
+    if msg.is_text:
+        print(msg.content, end="")
+    elif msg.is_tool_use:
+        print(f"[Tool: {msg.tool_name}]")
+```
+
+### Human-in-the-Loop
+
+```python
+from isa_agent_sdk import request_tool_permission, checkpoint
+
+# Request permission before dangerous operations
+authorized = await request_tool_permission(
+    "delete_file",
+    {"path": "important_data.txt"}
+)
+if authorized:
+    # proceed with deletion
+    pass
+
+# Create checkpoints for durable execution
+await checkpoint("about_to_deploy", {
+    "version": "1.0.0",
+    "environment": "production"
+})
+```
+
+### HTTP Client (for deployed apps)
+
+```python
+from isa_agent_sdk import ISAAgent
+
+client = ISAAgent(base_url="http://localhost:8000")
+
+# Non-streaming
+response = client.chat.create(
+    message="Explain quantum computing",
+    user_id="user123"
+)
+print(response.content)
+
+# Streaming
+for event in client.chat.stream(
+    message="Write a Python function",
+    user_id="user123"
+):
+    if event.is_content:
+        print(event.content, end="")
+```
+
+### Building a FastAPI Agent Service
+
+```python
+from fastapi import FastAPI
+from isa_agent_sdk import query, ISAAgentOptions
+
+app = FastAPI()
+
+@app.post("/query")
+async def agent_query(prompt: str):
+    responses = []
+    async for msg in query(prompt):
+        if msg.is_text:
+            responses.append(msg.content)
+    return {"response": "".join(responses)}
+```
+
+### A2A (Agent-to-Agent) Integration
+
+```python
+from fastapi import FastAPI
+from isa_agent_sdk import (
+    A2AAgentCard,
+    A2AClient,
+    A2AServerAdapter,
+    register_a2a_fastapi_routes,
+    build_auth_service_token_validator,
+)
+
+# Build agent card
+card = A2AAgentCard(
+    name="isA Agent",
+    url="https://agent.example.com/a2a",
+    token_url="https://auth.example.com/oauth/token",
+).to_dict()
+
+# Client call to remote A2A agent
+client = A2AClient("https://remote-agent.example.com")
+response = await client.send_message("https://remote-agent.example.com/a2a", "Hello from isA")
+
+# Server adapter maps A2A JSON-RPC -> isa_agent_sdk ask/query
+adapter = A2AServerAdapter()
+rpc_result = await adapter.handle_rpc({
+    "jsonrpc": "2.0",
+    "id": "1",
+    "method": "message/send",
+    "params": {"message": {"parts": [{"text": "Summarize this repo"}]}}
+})
+
+# Mount A2A endpoints in FastAPI
+app = FastAPI()
+register_a2a_fastapi_routes(
+    app,
+    adapter=adapter,
+    agent_card=card,
+    rpc_path="/a2a",
+    auth_validator=build_auth_service_token_validator(
+        "http://localhost:8201",
+        required_scopes=["a2a.invoke"],
+    ),
+)
+```
+
+## Execution Modes
+
+- **Reactive** - Responds to explicit requests
+- **Collaborative** - Checkpoints for human approval
+- **Proactive** - Anticipates needs, suggests actions
+
+## License
+
+MIT

isa_agent_sdk-0.2.0/README.md

@@ -0,0 +1,201 @@
+# isA Agent SDK
+
+[![Tests](https://github.com/xenoISA/isA_Agent_SDK/actions/workflows/test.yml/badge.svg)](https://github.com/xenoISA/isA_Agent_SDK/actions/workflows/test.yml)
+[![Dependency Audit](https://github.com/xenoISA/isA_Agent_SDK/actions/workflows/dependency-audit.yml/badge.svg)](https://github.com/xenoISA/isA_Agent_SDK/actions/workflows/dependency-audit.yml)
+
+A complete AI Agent SDK for building intelligent agents with advanced features. Compatible with Claude Agent SDK patterns, with additional capabilities.
+
+## Features
+
+- **Claude Agent SDK Compatible** - Familiar API patterns
+- **Streaming Messages** - Real-time response streaming
+- **Built-in Tools** - Read, Write, Edit, Bash, WebSearch, etc.
+- **MCP Integration** - Model Context Protocol with offline fallback
+- **Human-in-the-Loop** - Durable execution with checkpoints
+- **Skills System** - Local-first skill loading with MCP fallback
+- **Project Config** - `.isa` directory for project-specific settings
+- **Event Triggers** - Proactive agent activation
+- **Multiple Execution Modes** - Reactive, Collaborative, Proactive
+- **A2A Ready** - Agent Card + JSON-RPC client/server adapters
+- **Multi-Agent Swarm** - Dynamic agent handoffs with `[HANDOFF:]` directives
+- **DAG Task Execution** - Dependency-ordered workflows with parallel wavefronts
+- **Production Resilience** - Circuit breakers, bulkhead isolation, error classification, recovery playbooks
+- **Observability** - OpenTelemetry tracing, structured error logging, Prometheus metrics
+- **Intent-Driven Routing** - SenseNode classifies intent for automatic model tier selection
+- **Graceful Degradation** - Nodes skip optional operations when services are degraded
+- **3,500+ Tests** - Comprehensive coverage including chaos tests
+
+## Installation
+
+```bash
+pip install isa-agent-sdk
+
+# With FastAPI server support
+pip install isa-agent-sdk[server]
+
+# With OpenTelemetry tracing
+pip install isa-agent-sdk[observability]
+```
+
+## Project Setup
+
+Initialize a `.isa` directory for project-specific configuration:
+
+```bash
+mkdir -p .isa/skills
+```
+
+```
+my-project/
+├── .isa/
+│   ├── config.json          # Project configuration
+│   ├── settings.local.json  # MCP servers, permissions
+│   └── skills/              # Local skills (loaded first)
+│       └── my-skill/
+│           └── SKILL.md
+└── ...
+```
+
+Skills in `.isa/skills/` are loaded before MCP, allowing project-specific overrides.
+
+## Quick Start
+
+### Basic Query
+
+```python
+from isa_agent_sdk import query, ISAAgentOptions
+
+# Simple usage
+async for msg in query("Hello, world!"):
+    print(msg.content)
+
+# With options
+async for msg in query(
+    "Fix the bug in auth.py",
+    options=ISAAgentOptions(
+        allowed_tools=["Read", "Edit", "Bash"],
+        execution_mode="collaborative"
+    )
+):
+    if msg.is_text:
+        print(msg.content, end="")
+    elif msg.is_tool_use:
+        print(f"[Tool: {msg.tool_name}]")
+```
+
+### Human-in-the-Loop
+
+```python
+from isa_agent_sdk import request_tool_permission, checkpoint
+
+# Request permission before dangerous operations
+authorized = await request_tool_permission(
+    "delete_file",
+    {"path": "important_data.txt"}
+)
+if authorized:
+    # proceed with deletion
+    pass
+
+# Create checkpoints for durable execution
+await checkpoint("about_to_deploy", {
+    "version": "1.0.0",
+    "environment": "production"
+})
+```
+
+### HTTP Client (for deployed apps)
+
+```python
+from isa_agent_sdk import ISAAgent
+
+client = ISAAgent(base_url="http://localhost:8000")
+
+# Non-streaming
+response = client.chat.create(
+    message="Explain quantum computing",
+    user_id="user123"
+)
+print(response.content)
+
+# Streaming
+for event in client.chat.stream(
+    message="Write a Python function",
+    user_id="user123"
+):
+    if event.is_content:
+        print(event.content, end="")
+```
+
+### Building a FastAPI Agent Service
+
+```python
+from fastapi import FastAPI
+from isa_agent_sdk import query, ISAAgentOptions
+
+app = FastAPI()
+
+@app.post("/query")
+async def agent_query(prompt: str):
+    responses = []
+    async for msg in query(prompt):
+        if msg.is_text:
+            responses.append(msg.content)
+    return {"response": "".join(responses)}
+```
+
+### A2A (Agent-to-Agent) Integration
+
+```python
+from fastapi import FastAPI
+from isa_agent_sdk import (
+    A2AAgentCard,
+    A2AClient,
+    A2AServerAdapter,
+    register_a2a_fastapi_routes,
+    build_auth_service_token_validator,
+)
+
+# Build agent card
+card = A2AAgentCard(
+    name="isA Agent",
+    url="https://agent.example.com/a2a",
+    token_url="https://auth.example.com/oauth/token",
+).to_dict()
+
+# Client call to remote A2A agent
+client = A2AClient("https://remote-agent.example.com")
+response = await client.send_message("https://remote-agent.example.com/a2a", "Hello from isA")
+
+# Server adapter maps A2A JSON-RPC -> isa_agent_sdk ask/query
+adapter = A2AServerAdapter()
+rpc_result = await adapter.handle_rpc({
+    "jsonrpc": "2.0",
+    "id": "1",
+    "method": "message/send",
+    "params": {"message": {"parts": [{"text": "Summarize this repo"}]}}
+})
+
+# Mount A2A endpoints in FastAPI
+app = FastAPI()
+register_a2a_fastapi_routes(
+    app,
+    adapter=adapter,
+    agent_card=card,
+    rpc_path="/a2a",
+    auth_validator=build_auth_service_token_validator(
+        "http://localhost:8201",
+        required_scopes=["a2a.invoke"],
+    ),
+)
+```
+
+## Execution Modes
+
+- **Reactive** - Responds to explicit requests
+- **Collaborative** - Checkpoints for human approval
+- **Proactive** - Anticipates needs, suggests actions
+
+## License
+
+MIT