# Symbiont Python SDK
A Python SDK for interacting with the Symbiont Agent Runtime System, providing a streamlined interface for building AI-powered applications with agent capabilities, tool review workflows, and security analysis.
## Overview
The Symbiont Python SDK enables developers to integrate with the Symbiont platform, which provides intelligent agent runtime capabilities and comprehensive tool review workflows. This SDK handles authentication, HTTP requests, error handling, and provides typed models for working with Symbiont agents, tool reviews, and related resources.
## Installation
### Install from PyPI
```bash
pip install symbiont-sdk
```
### Install from Repository (Development)
For development or to get the latest features:
```bash
git clone https://github.com/thirdkeyai/symbiont-sdk-python.git
cd symbiont-sdk-python
pip install -e .
```
### Docker
The SDK is also available as a Docker image from GitHub Container Registry:
```bash
# Pull the latest image
docker pull ghcr.io/thirdkeyai/symbiont-sdk-python:latest
# Or pull a specific version
docker pull ghcr.io/thirdkeyai/symbiont-sdk-python:v0.2.0
```
#### Running with Docker
```bash
# Run interactively with Python REPL
docker run -it --rm ghcr.io/thirdkeyai/symbiont-sdk-python:latest
# Run with environment variables
docker run -it --rm \
-e SYMBIONT_API_KEY=your_api_key \
-e SYMBIONT_BASE_URL=http://host.docker.internal:8080/api/v1 \
ghcr.io/thirdkeyai/symbiont-sdk-python:latest
# Run a Python script from host
docker run --rm \
-v $(pwd):/workspace \
-w /workspace \
-e SYMBIONT_API_KEY=your_api_key \
ghcr.io/thirdkeyai/symbiont-sdk-python:latest \
python your_script.py
# Execute one-liner
docker run --rm \
-e SYMBIONT_API_KEY=your_api_key \
ghcr.io/thirdkeyai/symbiont-sdk-python:latest \
python -c "from symbiont import Client; print(Client().health_check())"
```
#### Building Docker Image Locally
```bash
# Build from source
git clone https://github.com/thirdkeyai/symbiont-sdk-python.git
cd symbiont-sdk-python
docker build -t symbiont-sdk:local .
# Run locally built image
docker run -it --rm symbiont-sdk:local
```
## Configuration
The SDK can be configured using environment variables in a `.env` file. Copy the provided `.env.example` file to get started:
```bash
cp .env.example .env
```
### Supported Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `SYMBIONT_API_KEY` | API key for authentication | None |
| `SYMBIONT_BASE_URL` | Base URL for the Symbiont API | `http://localhost:8080/api/v1` |
| `SYMBIONT_TIMEOUT` | Request timeout in seconds | `30` |
| `SYMBIONT_MAX_RETRIES` | Maximum retries for API calls | `3` |
### Example `.env` Configuration
```env
# API Configuration
SYMBIONT_API_KEY=your_api_key_here
SYMBIONT_BASE_URL=http://localhost:8080/api/v1
# Optional Settings
SYMBIONT_TIMEOUT=30
SYMBIONT_MAX_RETRIES=3
```
## Quick Start
### Basic Client Initialization
```python
from symbiont import Client
# Initialize with environment variables
client = Client()
# Or initialize with explicit parameters
client = Client(
api_key="your_api_key",
base_url="http://localhost:8080/api/v1"
)
```
### System Health Check
```python
from symbiont import Client
client = Client()
# Check system health
health = client.health_check()
print(f"Status: {health.status}")
print(f"Uptime: {health.uptime_seconds} seconds")
print(f"Version: {health.version}")
```
## API Reference
### Agent Management
#### List Agents
```python
# Get list of all agents
agents = client.list_agents()
print(f"Found {len(agents)} agents: {agents}")
```
#### Get Agent Status
```python
from symbiont import AgentState
# Get specific agent status
status = client.get_agent_status("agent-123")
print(f"Agent {status.agent_id} is {status.state}")
print(f"Memory usage: {status.resource_usage.memory_bytes} bytes")
print(f"CPU usage: {status.resource_usage.cpu_percent}%")
```
#### Create Agent
```python
from symbiont import Agent
# Create a new agent
agent_data = Agent(
id="my-agent",
name="My Assistant",
description="A helpful AI assistant",
system_prompt="You are a helpful assistant.",
tools=["web_search", "calculator"],
model="gpt-4",
temperature=0.7,
top_p=0.9,
max_tokens=1000
)
result = client.create_agent(agent_data)
print(f"Created agent: {result}")
```
### Workflow Execution
```python
from symbiont import WorkflowExecutionRequest
# Execute a workflow
workflow_request = WorkflowExecutionRequest(
workflow_id="data-analysis-workflow",
parameters={
"input_data": "path/to/data.csv",
"analysis_type": "statistical"
},
agent_id="agent-123" # Optional
)
result = client.execute_workflow(workflow_request)
print(f"Workflow result: {result}")
```
### Tool Review API
The Tool Review API provides comprehensive workflows for securely reviewing, analyzing, and signing MCP tools.
#### Submit Tool for Review
```python
from symbiont import (
ReviewSessionCreate, Tool, ToolProvider, ToolSchema
)
# Define a tool for review
tool = Tool(
name="example-calculator",
description="A simple calculator tool",
schema=ToolSchema(
type="object",
properties={
"operation": {
"type": "string",
"enum": ["add", "subtract", "multiply", "divide"]
},
"a": {"type": "number"},
"b": {"type": "number"}
},
required=["operation", "a", "b"]
),
provider=ToolProvider(
name="example-provider",
public_key_url="https://example.com/pubkey.pem"
)
)
# Submit for review
review_request = ReviewSessionCreate(
tool=tool,
submitted_by="developer@example.com",
priority="normal"
)
session = client.submit_tool_for_review(review_request)
print(f"Review session {session.review_id} created with status: {session.status}")
```
#### Monitor Review Progress
```python
from symbiont import ReviewStatus
# Get review session details
session = client.get_review_session("review-123")
print(f"Review status: {session.status}")
print(f"Submitted by: {session.submitted_by}")
# Check if analysis is complete
if session.state.analysis_id:
analysis = client.get_analysis_results(session.state.analysis_id)
print(f"Risk score: {analysis.risk_score}/100")
print(f"Found {len(analysis.findings)} security findings")
for finding in analysis.findings:
print(f"- {finding.severity.upper()}: {finding.title}")
```
#### List Review Sessions
```python
# List all review sessions with filtering
sessions = client.list_review_sessions(
page=1,
limit=10,
status="pending_review",
author="developer@example.com"
)
print(f"Found {len(sessions.sessions)} sessions")
for session in sessions.sessions:
print(f"- {session.review_id}: {session.tool.name} ({session.status})")
```
#### Wait for Review Completion
```python
# Wait for review to complete (with timeout)
try:
final_session = client.wait_for_review_completion("review-123", timeout=300)
print(f"Review completed with status: {final_session.status}")
if final_session.status == "approved":
print("Tool approved for signing!")
elif final_session.status == "rejected":
print("Tool rejected. Check review comments.")
except TimeoutError:
print("Review did not complete within timeout period")
```
#### Submit Human Review Decision
```python
from symbiont import HumanReviewDecision
# Submit reviewer decision
decision = HumanReviewDecision(
decision="approve",
comments="Tool looks safe after manual review",
reviewer_id="reviewer@example.com"
)
result = client.submit_human_review_decision("review-123", decision)
print(f"Decision submitted: {result}")
```
#### Sign Approved Tool
```python
from symbiont import SigningRequest
# Sign an approved tool
signing_request = SigningRequest(
review_id="review-123",
signing_key_id="key-456"
)
signature = client.sign_approved_tool(signing_request)
print(f"Tool signed at {signature.signed_at}")
print(f"Signature: {signature.signature}")
# Get signed tool information
signed_tool = client.get_signed_tool("review-123")
print(f"Signed tool: {signed_tool.tool.name}")
print(f"Signature algorithm: {signed_tool.signature_algorithm}")
```
## Error Handling
The SDK provides specific exception classes for different types of errors:
```python
from symbiont import (
Client, APIError, AuthenticationError,
NotFoundError, RateLimitError, SymbiontError
)
client = Client()
try:
# Make an API request
session = client.get_review_session("non-existent-review")
except AuthenticationError as e:
print(f"Authentication failed: {e}")
print("Please check your API key")
except NotFoundError as e:
print(f"Resource not found: {e}")
print(f"Response: {e.response_text}")
except RateLimitError as e:
print(f"Rate limit exceeded: {e}")
print("Please wait before making more requests")
except APIError as e:
print(f"API error (status {e.status_code}): {e}")
print(f"Response: {e.response_text}")
except SymbiontError as e:
print(f"SDK error: {e}")
except Exception as e:
print(f"Unexpected error: {e}")
```
### Exception Hierarchy
- `SymbiontError` - Base exception for all SDK errors
- `APIError` - Generic API errors (4xx and 5xx status codes)
- `AuthenticationError` - 401 Unauthorized responses
- `NotFoundError` - 404 Not Found responses
- `RateLimitError` - 429 Too Many Requests responses
## Advanced Usage
### Working with Models
All API responses are automatically converted to typed Pydantic models:
```python
from symbiont import ReviewSession, SecurityFinding, FindingSeverity
# Models provide type safety and validation
session = client.get_review_session("review-123")
# Access typed attributes
session_id: str = session.review_id
status: ReviewStatus = session.status
submitted_time: datetime = session.submitted_at
# Work with nested models
if session.state.critical_findings:
for finding in session.state.critical_findings:
finding_id: str = finding.finding_id
severity: FindingSeverity = finding.severity
confidence: float = finding.confidence
```
### Batch Operations
```python
# Submit multiple tools for review
tools_to_review = [tool1, tool2, tool3]
review_sessions = []
for tool in tools_to_review:
request = ReviewSessionCreate(
tool=tool,
submitted_by="batch@example.com"
)
session = client.submit_tool_for_review(request)
review_sessions.append(session)
print(f"Submitted {len(review_sessions)} tools for review")
# Monitor all sessions
for session in review_sessions:
current_status = client.get_review_session(session.review_id)
print(f"Tool {current_status.tool.name}: {current_status.status}")
```
## Testing
### Install Development Dependencies
```bash
pip install -r requirements-dev.txt
```
### Run Tests
```bash
# Run all tests
pytest
# Run tests with coverage
pytest --cov=symbiont
# Run specific test file
pytest tests/test_client.py
# Run tests with verbose output
pytest -v
```
### Running Tests in Development
```bash
# Create a virtual environment (recommended)
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt
# Run tests
pytest
```
## Requirements
- Python 3.7+
- requests
- pydantic
- python-dotenv
## What's New in v0.3.0
### Major New Features
- **Secrets Management System**: Complete secrets management with HashiCorp Vault, encrypted files, and OS keychain integration
- **MCP Management**: Enhanced Model Context Protocol server management and tool integration
- **Vector Database & RAG**: Knowledge management with vector similarity search and retrieval-augmented generation
- **Agent DSL Operations**: DSL compilation and agent deployment capabilities
- **Enhanced Monitoring**: Comprehensive system and agent metrics
- **Security Enhancements**: Advanced signing and verification workflows
### Secrets Management
```python
from symbiont import (
Client, SecretBackendConfig, SecretBackendType,
VaultConfig, VaultAuthMethod, SecretRequest
)
client = Client()
# Configure HashiCorp Vault backend
vault_config = VaultConfig(
url="https://vault.example.com",
auth_method=VaultAuthMethod.TOKEN,
token="hvs.abc123..."
)
backend_config = SecretBackendConfig(
backend_type=SecretBackendType.VAULT,
vault_config=vault_config
)
client.configure_secret_backend(backend_config)
# Store and retrieve secrets
secret_request = SecretRequest(
agent_id="agent-123",
secret_name="api_key",
secret_value="secret_value_here",
description="API key for external service"
)
response = client.store_secret(secret_request)
print(f"Secret stored: {response.secret_name}")
# Retrieve secret
secret_value = client.get_secret("agent-123", "api_key")
print(f"Retrieved secret: {secret_value}")
# List all secrets for an agent
secrets_list = client.list_secrets("agent-123")
print(f"Agent secrets: {secrets_list.secrets}")
```
### MCP Management
```python
from symbiont import McpServerConfig
# Add MCP server
mcp_config = McpServerConfig(
name="filesystem-server",
command=["npx", "@modelcontextprotocol/server-filesystem", "/tmp"],
env={"NODE_ENV": "production"},
timeout_seconds=30
)
client.add_mcp_server(mcp_config)
# Connect to server
client.connect_mcp_server("filesystem-server")
# List available tools and resources
tools = client.list_mcp_tools("filesystem-server")
resources = client.list_mcp_resources("filesystem-server")
print(f"Available tools: {[tool.name for tool in tools]}")
print(f"Available resources: {[resource.uri for resource in resources]}")
# Get connection status
connection_info = client.get_mcp_server("filesystem-server")
print(f"Status: {connection_info.status}")
print(f"Tools count: {connection_info.tools_count}")
```
### Vector Database & RAG
```python
from symbiont import (
KnowledgeItem, VectorMetadata, KnowledgeSourceType,
VectorSearchRequest, ContextQuery
)
# Add knowledge items
metadata = VectorMetadata(
source="documentation.md",
source_type=KnowledgeSourceType.DOCUMENT,
timestamp=datetime.now(),
agent_id="agent-123"
)
knowledge_item = KnowledgeItem(
id="doc-001",
content="This is important documentation about the system...",
metadata=metadata
)
client.add_knowledge_item(knowledge_item)
# Search knowledge base
search_request = VectorSearchRequest(
query="How do I configure the system?",
agent_id="agent-123",
source_types=[KnowledgeSourceType.DOCUMENT],
limit=5,
similarity_threshold=0.7
)
search_results = client.search_knowledge(search_request)
for result in search_results.results:
print(f"Score: {result.similarity_score}")
print(f"Content: {result.item.content[:100]}...")
# Get context for RAG operations
context_query = ContextQuery(
query="How do I set up authentication?",
agent_id="agent-123",
max_context_items=3
)
context = client.get_context(context_query)
print(f"Retrieved {len(context.context_items)} context items")
print(f"Sources: {context.sources}")
```
### Agent DSL Operations
```python
from symbiont import DslCompileRequest, AgentDeployRequest
# Compile DSL code
dsl_code = """
agent webhook_handler {
name: "Webhook Handler"
description: "Handles incoming webhooks"
trigger github_webhook {
on_push: main
}
action process_webhook {
validate_signature()
parse_payload()
trigger_workflow()
}
}
"""
compile_request = DslCompileRequest(
dsl_content=dsl_code,
agent_name="webhook_handler",
validate_only=False
)
compile_result = client.compile_dsl(compile_request)
if compile_result.success:
print(f"Compiled successfully: {compile_result.agent_id}")
# Deploy the agent
deploy_request = AgentDeployRequest(
agent_id=compile_result.agent_id,
environment="production",
config_overrides={"max_concurrent_tasks": 10}
)
deployment = client.deploy_agent(deploy_request)
print(f"Deployed: {deployment.deployment_id}")
print(f"Endpoint: {deployment.endpoint_url}")
else:
print(f"Compilation errors: {compile_result.errors}")
```
### Enhanced Monitoring
```python
# Get comprehensive system metrics
system_metrics = client.get_metrics()
print(f"Memory usage: {system_metrics.memory_usage_percent}%")
print(f"CPU usage: {system_metrics.cpu_usage_percent}%")
print(f"Active agents: {system_metrics.active_agents}")
print(f"Vector DB items: {system_metrics.vector_db_items}")
print(f"MCP connections: {system_metrics.mcp_connections}")
# Get agent-specific metrics
agent_metrics = client.get_agent_metrics("agent-123")
print(f"Tasks completed: {agent_metrics.tasks_completed}")
print(f"Average response time: {agent_metrics.average_response_time_ms}ms")
print(f"Agent uptime: {agent_metrics.uptime_seconds}s")
```
## Previous Release Notes
### v0.2.0
- **Tool Review API**: Complete implementation of tool review workflows
- **Runtime API**: Agent management, workflow execution, and system metrics
- **Enhanced Models**: Comprehensive type definitions for all API responses
- **Better Error Handling**: Specific exceptions for different error conditions
- **Improved Documentation**: Complete API reference with examples
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
### Setting up for Development
1. Fork the repository
2. Clone your fork locally
3. Set up development environment:
```bash
git clone https://github.com/yourusername/symbiont-sdk-python.git
cd symbiont-sdk-python
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
pip install -r requirements-dev.txt
```
4. Run tests to ensure everything works:
```bash
pytest
ruff check symbiont/
bandit -r symbiont/
```
5. Make your changes and add tests
6. Submit a pull request
### Release Process
Releases are automated through GitHub Actions:
1. **CI/CD**: Every push/PR triggers testing across Python 3.8-3.12
2. **Release**: Create a new tag with format `v*.*.*` (e.g., `v0.2.0`) to trigger:
- Automated testing
- Package building
- PyPI publishing
- GitHub release creation
#### Setting up PyPI Publishing (Maintainers)
For repository maintainers, set up these GitHub repository secrets:
- `PYPI_API_TOKEN`: PyPI API token for automated publishing
To create a PyPI API token:
1. Go to PyPI Account Settings → API tokens
2. Create new token with scope for this project
3. Add to GitHub repository secrets as `PYPI_API_TOKEN`
#### Container Registry Publishing
The Docker workflow automatically publishes container images to GitHub Container Registry:
- **Latest image**: Published on every push to main branch (`ghcr.io/thirdkeyai/symbiont-sdk-python:latest`)
- **Version tags**: Published on release tags (`ghcr.io/thirdkeyai/symbiont-sdk-python:v0.2.0`)
- **Branch tags**: Published for feature branches during development
Images are built for multiple architectures (linux/amd64, linux/arm64) and include:
- Multi-stage optimized builds for smaller image size
- Non-root user execution for security
- Health checks for container monitoring
- Full SDK functionality with all dependencies
Both the release workflow (PyPI) and Docker workflow (container registry) will automatically run when a new tag is pushed.
Raw data
{
"_id": null,
"home_page": "https://github.com/thirdkeyai/symbiont-sdk-python",
"name": "symbiont-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "symbiont, sdk, api, ai, agents, tool-review, runtime",
"author": "Jascha Wanger / ThirdKey.ai",
"author_email": "\"Jascha Wanger / ThirdKey.ai\" <oss@symbiont.dev>",
"download_url": "https://files.pythonhosted.org/packages/2d/9b/c658ba8232eb05cb309730d60b6f8d6c8b8c6c8f2e183ea4678a154e12ac/symbiont_sdk-0.3.0.tar.gz",
"platform": null,
"description": "# Symbiont Python SDK\n\nA Python SDK for interacting with the Symbiont Agent Runtime System, providing a streamlined interface for building AI-powered applications with agent capabilities, tool review workflows, and security analysis.\n\n## Overview\n\nThe Symbiont Python SDK enables developers to integrate with the Symbiont platform, which provides intelligent agent runtime capabilities and comprehensive tool review workflows. This SDK handles authentication, HTTP requests, error handling, and provides typed models for working with Symbiont agents, tool reviews, and related resources.\n\n## Installation\n\n### Install from PyPI\n\n```bash\npip install symbiont-sdk\n```\n\n### Install from Repository (Development)\n\nFor development or to get the latest features:\n\n```bash\ngit clone https://github.com/thirdkeyai/symbiont-sdk-python.git\ncd symbiont-sdk-python\npip install -e .\n```\n\n### Docker\n\nThe SDK is also available as a Docker image from GitHub Container Registry:\n\n```bash\n# Pull the latest image\ndocker pull ghcr.io/thirdkeyai/symbiont-sdk-python:latest\n\n# Or pull a specific version\ndocker pull ghcr.io/thirdkeyai/symbiont-sdk-python:v0.2.0\n```\n\n#### Running with Docker\n\n```bash\n# Run interactively with Python REPL\ndocker run -it --rm ghcr.io/thirdkeyai/symbiont-sdk-python:latest\n\n# Run with environment variables\ndocker run -it --rm \\\n -e SYMBIONT_API_KEY=your_api_key \\\n -e SYMBIONT_BASE_URL=http://host.docker.internal:8080/api/v1 \\\n ghcr.io/thirdkeyai/symbiont-sdk-python:latest\n\n# Run a Python script from host\ndocker run --rm \\\n -v $(pwd):/workspace \\\n -w /workspace \\\n -e SYMBIONT_API_KEY=your_api_key \\\n ghcr.io/thirdkeyai/symbiont-sdk-python:latest \\\n python your_script.py\n\n# Execute one-liner\ndocker run --rm \\\n -e SYMBIONT_API_KEY=your_api_key \\\n ghcr.io/thirdkeyai/symbiont-sdk-python:latest \\\n python -c \"from symbiont import Client; print(Client().health_check())\"\n```\n\n#### Building Docker Image Locally\n\n```bash\n# Build from source\ngit clone https://github.com/thirdkeyai/symbiont-sdk-python.git\ncd symbiont-sdk-python\ndocker build -t symbiont-sdk:local .\n\n# Run locally built image\ndocker run -it --rm symbiont-sdk:local\n```\n\n## Configuration\n\nThe SDK can be configured using environment variables in a `.env` file. Copy the provided `.env.example` file to get started:\n\n```bash\ncp .env.example .env\n```\n\n### Supported Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `SYMBIONT_API_KEY` | API key for authentication | None |\n| `SYMBIONT_BASE_URL` | Base URL for the Symbiont API | `http://localhost:8080/api/v1` |\n| `SYMBIONT_TIMEOUT` | Request timeout in seconds | `30` |\n| `SYMBIONT_MAX_RETRIES` | Maximum retries for API calls | `3` |\n\n### Example `.env` Configuration\n\n```env\n# API Configuration\nSYMBIONT_API_KEY=your_api_key_here\nSYMBIONT_BASE_URL=http://localhost:8080/api/v1\n\n# Optional Settings\nSYMBIONT_TIMEOUT=30\nSYMBIONT_MAX_RETRIES=3\n```\n\n## Quick Start\n\n### Basic Client Initialization\n\n```python\nfrom symbiont import Client\n\n# Initialize with environment variables\nclient = Client()\n\n# Or initialize with explicit parameters\nclient = Client(\n api_key=\"your_api_key\",\n base_url=\"http://localhost:8080/api/v1\"\n)\n```\n\n### System Health Check\n\n```python\nfrom symbiont import Client\n\nclient = Client()\n\n# Check system health\nhealth = client.health_check()\nprint(f\"Status: {health.status}\")\nprint(f\"Uptime: {health.uptime_seconds} seconds\")\nprint(f\"Version: {health.version}\")\n```\n\n## API Reference\n\n### Agent Management\n\n#### List Agents\n\n```python\n# Get list of all agents\nagents = client.list_agents()\nprint(f\"Found {len(agents)} agents: {agents}\")\n```\n\n#### Get Agent Status\n\n```python\nfrom symbiont import AgentState\n\n# Get specific agent status\nstatus = client.get_agent_status(\"agent-123\")\nprint(f\"Agent {status.agent_id} is {status.state}\")\nprint(f\"Memory usage: {status.resource_usage.memory_bytes} bytes\")\nprint(f\"CPU usage: {status.resource_usage.cpu_percent}%\")\n```\n\n#### Create Agent\n\n```python\nfrom symbiont import Agent\n\n# Create a new agent\nagent_data = Agent(\n id=\"my-agent\",\n name=\"My Assistant\",\n description=\"A helpful AI assistant\",\n system_prompt=\"You are a helpful assistant.\",\n tools=[\"web_search\", \"calculator\"],\n model=\"gpt-4\",\n temperature=0.7,\n top_p=0.9,\n max_tokens=1000\n)\n\nresult = client.create_agent(agent_data)\nprint(f\"Created agent: {result}\")\n```\n\n### Workflow Execution\n\n```python\nfrom symbiont import WorkflowExecutionRequest\n\n# Execute a workflow\nworkflow_request = WorkflowExecutionRequest(\n workflow_id=\"data-analysis-workflow\",\n parameters={\n \"input_data\": \"path/to/data.csv\",\n \"analysis_type\": \"statistical\"\n },\n agent_id=\"agent-123\" # Optional\n)\n\nresult = client.execute_workflow(workflow_request)\nprint(f\"Workflow result: {result}\")\n```\n\n### Tool Review API\n\nThe Tool Review API provides comprehensive workflows for securely reviewing, analyzing, and signing MCP tools.\n\n#### Submit Tool for Review\n\n```python\nfrom symbiont import (\n ReviewSessionCreate, Tool, ToolProvider, ToolSchema\n)\n\n# Define a tool for review\ntool = Tool(\n name=\"example-calculator\",\n description=\"A simple calculator tool\",\n schema=ToolSchema(\n type=\"object\",\n properties={\n \"operation\": {\n \"type\": \"string\",\n \"enum\": [\"add\", \"subtract\", \"multiply\", \"divide\"]\n },\n \"a\": {\"type\": \"number\"},\n \"b\": {\"type\": \"number\"}\n },\n required=[\"operation\", \"a\", \"b\"]\n ),\n provider=ToolProvider(\n name=\"example-provider\",\n public_key_url=\"https://example.com/pubkey.pem\"\n )\n)\n\n# Submit for review\nreview_request = ReviewSessionCreate(\n tool=tool,\n submitted_by=\"developer@example.com\",\n priority=\"normal\"\n)\n\nsession = client.submit_tool_for_review(review_request)\nprint(f\"Review session {session.review_id} created with status: {session.status}\")\n```\n\n#### Monitor Review Progress\n\n```python\nfrom symbiont import ReviewStatus\n\n# Get review session details\nsession = client.get_review_session(\"review-123\")\nprint(f\"Review status: {session.status}\")\nprint(f\"Submitted by: {session.submitted_by}\")\n\n# Check if analysis is complete\nif session.state.analysis_id:\n analysis = client.get_analysis_results(session.state.analysis_id)\n print(f\"Risk score: {analysis.risk_score}/100\")\n print(f\"Found {len(analysis.findings)} security findings\")\n \n for finding in analysis.findings:\n print(f\"- {finding.severity.upper()}: {finding.title}\")\n```\n\n#### List Review Sessions\n\n```python\n# List all review sessions with filtering\nsessions = client.list_review_sessions(\n page=1,\n limit=10,\n status=\"pending_review\",\n author=\"developer@example.com\"\n)\n\nprint(f\"Found {len(sessions.sessions)} sessions\")\nfor session in sessions.sessions:\n print(f\"- {session.review_id}: {session.tool.name} ({session.status})\")\n```\n\n#### Wait for Review Completion\n\n```python\n# Wait for review to complete (with timeout)\ntry:\n final_session = client.wait_for_review_completion(\"review-123\", timeout=300)\n print(f\"Review completed with status: {final_session.status}\")\n \n if final_session.status == \"approved\":\n print(\"Tool approved for signing!\")\n elif final_session.status == \"rejected\":\n print(\"Tool rejected. Check review comments.\")\n \nexcept TimeoutError:\n print(\"Review did not complete within timeout period\")\n```\n\n#### Submit Human Review Decision\n\n```python\nfrom symbiont import HumanReviewDecision\n\n# Submit reviewer decision\ndecision = HumanReviewDecision(\n decision=\"approve\",\n comments=\"Tool looks safe after manual review\",\n reviewer_id=\"reviewer@example.com\"\n)\n\nresult = client.submit_human_review_decision(\"review-123\", decision)\nprint(f\"Decision submitted: {result}\")\n```\n\n#### Sign Approved Tool\n\n```python\nfrom symbiont import SigningRequest\n\n# Sign an approved tool\nsigning_request = SigningRequest(\n review_id=\"review-123\",\n signing_key_id=\"key-456\"\n)\n\nsignature = client.sign_approved_tool(signing_request)\nprint(f\"Tool signed at {signature.signed_at}\")\nprint(f\"Signature: {signature.signature}\")\n\n# Get signed tool information\nsigned_tool = client.get_signed_tool(\"review-123\")\nprint(f\"Signed tool: {signed_tool.tool.name}\")\nprint(f\"Signature algorithm: {signed_tool.signature_algorithm}\")\n```\n\n## Error Handling\n\nThe SDK provides specific exception classes for different types of errors:\n\n```python\nfrom symbiont import (\n Client, APIError, AuthenticationError, \n NotFoundError, RateLimitError, SymbiontError\n)\n\nclient = Client()\n\ntry:\n # Make an API request\n session = client.get_review_session(\"non-existent-review\")\n \nexcept AuthenticationError as e:\n print(f\"Authentication failed: {e}\")\n print(\"Please check your API key\")\n \nexcept NotFoundError as e:\n print(f\"Resource not found: {e}\")\n print(f\"Response: {e.response_text}\")\n \nexcept RateLimitError as e:\n print(f\"Rate limit exceeded: {e}\")\n print(\"Please wait before making more requests\")\n \nexcept APIError as e:\n print(f\"API error (status {e.status_code}): {e}\")\n print(f\"Response: {e.response_text}\")\n \nexcept SymbiontError as e:\n print(f\"SDK error: {e}\")\n \nexcept Exception as e:\n print(f\"Unexpected error: {e}\")\n```\n\n### Exception Hierarchy\n\n- `SymbiontError` - Base exception for all SDK errors\n - `APIError` - Generic API errors (4xx and 5xx status codes)\n - `AuthenticationError` - 401 Unauthorized responses\n - `NotFoundError` - 404 Not Found responses\n - `RateLimitError` - 429 Too Many Requests responses\n\n## Advanced Usage\n\n### Working with Models\n\nAll API responses are automatically converted to typed Pydantic models:\n\n```python\nfrom symbiont import ReviewSession, SecurityFinding, FindingSeverity\n\n# Models provide type safety and validation\nsession = client.get_review_session(\"review-123\")\n\n# Access typed attributes\nsession_id: str = session.review_id\nstatus: ReviewStatus = session.status\nsubmitted_time: datetime = session.submitted_at\n\n# Work with nested models\nif session.state.critical_findings:\n for finding in session.state.critical_findings:\n finding_id: str = finding.finding_id\n severity: FindingSeverity = finding.severity\n confidence: float = finding.confidence\n```\n\n### Batch Operations\n\n```python\n# Submit multiple tools for review\ntools_to_review = [tool1, tool2, tool3]\nreview_sessions = []\n\nfor tool in tools_to_review:\n request = ReviewSessionCreate(\n tool=tool,\n submitted_by=\"batch@example.com\"\n )\n session = client.submit_tool_for_review(request)\n review_sessions.append(session)\n\nprint(f\"Submitted {len(review_sessions)} tools for review\")\n\n# Monitor all sessions\nfor session in review_sessions:\n current_status = client.get_review_session(session.review_id)\n print(f\"Tool {current_status.tool.name}: {current_status.status}\")\n```\n\n## Testing\n\n### Install Development Dependencies\n\n```bash\npip install -r requirements-dev.txt\n```\n\n### Run Tests\n\n```bash\n# Run all tests\npytest\n\n# Run tests with coverage\npytest --cov=symbiont\n\n# Run specific test file\npytest tests/test_client.py\n\n# Run tests with verbose output\npytest -v\n```\n\n### Running Tests in Development\n\n```bash\n# Create a virtual environment (recommended)\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install dependencies\npip install -r requirements.txt\npip install -r requirements-dev.txt\n\n# Run tests\npytest\n```\n\n## Requirements\n\n- Python 3.7+\n- requests\n- pydantic\n- python-dotenv\n\n## What's New in v0.3.0\n\n### Major New Features\n\n- **Secrets Management System**: Complete secrets management with HashiCorp Vault, encrypted files, and OS keychain integration\n- **MCP Management**: Enhanced Model Context Protocol server management and tool integration\n- **Vector Database & RAG**: Knowledge management with vector similarity search and retrieval-augmented generation\n- **Agent DSL Operations**: DSL compilation and agent deployment capabilities\n- **Enhanced Monitoring**: Comprehensive system and agent metrics\n- **Security Enhancements**: Advanced signing and verification workflows\n\n### Secrets Management\n\n```python\nfrom symbiont import (\n Client, SecretBackendConfig, SecretBackendType,\n VaultConfig, VaultAuthMethod, SecretRequest\n)\n\nclient = Client()\n\n# Configure HashiCorp Vault backend\nvault_config = VaultConfig(\n url=\"https://vault.example.com\",\n auth_method=VaultAuthMethod.TOKEN,\n token=\"hvs.abc123...\"\n)\n\nbackend_config = SecretBackendConfig(\n backend_type=SecretBackendType.VAULT,\n vault_config=vault_config\n)\n\nclient.configure_secret_backend(backend_config)\n\n# Store and retrieve secrets\nsecret_request = SecretRequest(\n agent_id=\"agent-123\",\n secret_name=\"api_key\",\n secret_value=\"secret_value_here\",\n description=\"API key for external service\"\n)\n\nresponse = client.store_secret(secret_request)\nprint(f\"Secret stored: {response.secret_name}\")\n\n# Retrieve secret\nsecret_value = client.get_secret(\"agent-123\", \"api_key\")\nprint(f\"Retrieved secret: {secret_value}\")\n\n# List all secrets for an agent\nsecrets_list = client.list_secrets(\"agent-123\")\nprint(f\"Agent secrets: {secrets_list.secrets}\")\n```\n\n### MCP Management\n\n```python\nfrom symbiont import McpServerConfig\n\n# Add MCP server\nmcp_config = McpServerConfig(\n name=\"filesystem-server\",\n command=[\"npx\", \"@modelcontextprotocol/server-filesystem\", \"/tmp\"],\n env={\"NODE_ENV\": \"production\"},\n timeout_seconds=30\n)\n\nclient.add_mcp_server(mcp_config)\n\n# Connect to server\nclient.connect_mcp_server(\"filesystem-server\")\n\n# List available tools and resources\ntools = client.list_mcp_tools(\"filesystem-server\")\nresources = client.list_mcp_resources(\"filesystem-server\")\n\nprint(f\"Available tools: {[tool.name for tool in tools]}\")\nprint(f\"Available resources: {[resource.uri for resource in resources]}\")\n\n# Get connection status\nconnection_info = client.get_mcp_server(\"filesystem-server\")\nprint(f\"Status: {connection_info.status}\")\nprint(f\"Tools count: {connection_info.tools_count}\")\n```\n\n### Vector Database & RAG\n\n```python\nfrom symbiont import (\n KnowledgeItem, VectorMetadata, KnowledgeSourceType,\n VectorSearchRequest, ContextQuery\n)\n\n# Add knowledge items\nmetadata = VectorMetadata(\n source=\"documentation.md\",\n source_type=KnowledgeSourceType.DOCUMENT,\n timestamp=datetime.now(),\n agent_id=\"agent-123\"\n)\n\nknowledge_item = KnowledgeItem(\n id=\"doc-001\",\n content=\"This is important documentation about the system...\",\n metadata=metadata\n)\n\nclient.add_knowledge_item(knowledge_item)\n\n# Search knowledge base\nsearch_request = VectorSearchRequest(\n query=\"How do I configure the system?\",\n agent_id=\"agent-123\",\n source_types=[KnowledgeSourceType.DOCUMENT],\n limit=5,\n similarity_threshold=0.7\n)\n\nsearch_results = client.search_knowledge(search_request)\nfor result in search_results.results:\n print(f\"Score: {result.similarity_score}\")\n print(f\"Content: {result.item.content[:100]}...\")\n\n# Get context for RAG operations\ncontext_query = ContextQuery(\n query=\"How do I set up authentication?\",\n agent_id=\"agent-123\",\n max_context_items=3\n)\n\ncontext = client.get_context(context_query)\nprint(f\"Retrieved {len(context.context_items)} context items\")\nprint(f\"Sources: {context.sources}\")\n```\n\n### Agent DSL Operations\n\n```python\nfrom symbiont import DslCompileRequest, AgentDeployRequest\n\n# Compile DSL code\ndsl_code = \"\"\"\nagent webhook_handler {\n name: \"Webhook Handler\"\n description: \"Handles incoming webhooks\"\n \n trigger github_webhook {\n on_push: main\n }\n \n action process_webhook {\n validate_signature()\n parse_payload()\n trigger_workflow()\n }\n}\n\"\"\"\n\ncompile_request = DslCompileRequest(\n dsl_content=dsl_code,\n agent_name=\"webhook_handler\",\n validate_only=False\n)\n\ncompile_result = client.compile_dsl(compile_request)\nif compile_result.success:\n print(f\"Compiled successfully: {compile_result.agent_id}\")\n \n # Deploy the agent\n deploy_request = AgentDeployRequest(\n agent_id=compile_result.agent_id,\n environment=\"production\",\n config_overrides={\"max_concurrent_tasks\": 10}\n )\n \n deployment = client.deploy_agent(deploy_request)\n print(f\"Deployed: {deployment.deployment_id}\")\n print(f\"Endpoint: {deployment.endpoint_url}\")\nelse:\n print(f\"Compilation errors: {compile_result.errors}\")\n```\n\n### Enhanced Monitoring\n\n```python\n# Get comprehensive system metrics\nsystem_metrics = client.get_metrics()\nprint(f\"Memory usage: {system_metrics.memory_usage_percent}%\")\nprint(f\"CPU usage: {system_metrics.cpu_usage_percent}%\")\nprint(f\"Active agents: {system_metrics.active_agents}\")\nprint(f\"Vector DB items: {system_metrics.vector_db_items}\")\nprint(f\"MCP connections: {system_metrics.mcp_connections}\")\n\n# Get agent-specific metrics\nagent_metrics = client.get_agent_metrics(\"agent-123\")\nprint(f\"Tasks completed: {agent_metrics.tasks_completed}\")\nprint(f\"Average response time: {agent_metrics.average_response_time_ms}ms\")\nprint(f\"Agent uptime: {agent_metrics.uptime_seconds}s\")\n```\n\n## Previous Release Notes\n\n### v0.2.0\n\n- **Tool Review API**: Complete implementation of tool review workflows\n- **Runtime API**: Agent management, workflow execution, and system metrics\n- **Enhanced Models**: Comprehensive type definitions for all API responses\n- **Better Error Handling**: Specific exceptions for different error conditions\n- **Improved Documentation**: Complete API reference with examples\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n### Setting up for Development\n\n1. Fork the repository\n2. Clone your fork locally\n3. Set up development environment:\n\n```bash\ngit clone https://github.com/yourusername/symbiont-sdk-python.git\ncd symbiont-sdk-python\npython -m venv .venv\nsource .venv/bin/activate # On Windows: .venv\\Scripts\\activate\npip install -r requirements.txt\npip install -r requirements-dev.txt\n```\n\n4. Run tests to ensure everything works:\n\n```bash\npytest\nruff check symbiont/\nbandit -r symbiont/\n```\n\n5. Make your changes and add tests\n6. Submit a pull request\n\n### Release Process\n\nReleases are automated through GitHub Actions:\n\n1. **CI/CD**: Every push/PR triggers testing across Python 3.8-3.12\n2. **Release**: Create a new tag with format `v*.*.*` (e.g., `v0.2.0`) to trigger:\n - Automated testing\n - Package building\n - PyPI publishing\n - GitHub release creation\n\n#### Setting up PyPI Publishing (Maintainers)\n\nFor repository maintainers, set up these GitHub repository secrets:\n\n- `PYPI_API_TOKEN`: PyPI API token for automated publishing\n\nTo create a PyPI API token:\n1. Go to PyPI Account Settings \u2192 API tokens\n2. Create new token with scope for this project\n3. Add to GitHub repository secrets as `PYPI_API_TOKEN`\n\n#### Container Registry Publishing\n\nThe Docker workflow automatically publishes container images to GitHub Container Registry:\n\n- **Latest image**: Published on every push to main branch (`ghcr.io/thirdkeyai/symbiont-sdk-python:latest`)\n- **Version tags**: Published on release tags (`ghcr.io/thirdkeyai/symbiont-sdk-python:v0.2.0`)\n- **Branch tags**: Published for feature branches during development\n\nImages are built for multiple architectures (linux/amd64, linux/arm64) and include:\n- Multi-stage optimized builds for smaller image size\n- Non-root user execution for security\n- Health checks for container monitoring\n- Full SDK functionality with all dependencies\n\nBoth the release workflow (PyPI) and Docker workflow (container registry) will automatically run when a new tag is pushed.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python SDK for Symbiont platform with Tool Review and Runtime APIs",
"version": "0.3.0",
"project_urls": {
"Bug Tracker": "https://github.com/thirdkeyai/symbiont-sdk-python/issues",
"Documentation": "https://github.com/thirdkeyai/symbiont-sdk-python#readme",
"Homepage": "https://github.com/thirdkeyai/symbiont-sdk-python",
"Repository": "https://github.com/thirdkeyai/symbiont-sdk-python"
},
"split_keywords": [
"symbiont",
" sdk",
" api",
" ai",
" agents",
" tool-review",
" runtime"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "bb7079bfc0fa281fb7ed590f9dc8bc73886847438ea2af368b32335c67b465c2",
"md5": "283e8f8ad4f77c0e94f90ba512c56304",
"sha256": "c7fdd3125b24f4bb1e59ea217fe145d9954091719cf766d0fc824435fbbc7bbf"
},
"downloads": -1,
"filename": "symbiont_sdk-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "283e8f8ad4f77c0e94f90ba512c56304",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 19578,
"upload_time": "2025-07-31T22:38:51",
"upload_time_iso_8601": "2025-07-31T22:38:51.710853Z",
"url": "https://files.pythonhosted.org/packages/bb/70/79bfc0fa281fb7ed590f9dc8bc73886847438ea2af368b32335c67b465c2/symbiont_sdk-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2d9bc658ba8232eb05cb309730d60b6f8d6c8b8c6c8f2e183ea4678a154e12ac",
"md5": "a605853b79217c6e350df6ebc120f6c0",
"sha256": "2b6cea46ef60362e105884502eccb10fcd0a6da1bcefd0be67d874ce8f75ad62"
},
"downloads": -1,
"filename": "symbiont_sdk-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "a605853b79217c6e350df6ebc120f6c0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 29561,
"upload_time": "2025-07-31T22:38:53",
"upload_time_iso_8601": "2025-07-31T22:38:53.097041Z",
"url": "https://files.pythonhosted.org/packages/2d/9b/c658ba8232eb05cb309730d60b6f8d6c8b8c6c8f2e183ea4678a154e12ac/symbiont_sdk-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-31 22:38:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "thirdkeyai",
"github_project": "symbiont-sdk-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": []
},
{
"name": "pydantic",
"specs": []
},
{
"name": "python-dotenv",
"specs": []
}
],
"lcname": "symbiont-sdk"
}