Metadata-Version: 2.4
Name: qodo-sdk
Version: 0.1.0
Summary: Qodo Python SDK for AI-powered agents
Project-URL: Homepage, https://qodo.ai
Project-URL: Documentation, https://docs.qodo.ai/qodo-documentation/
Author-email: Qodo <support@qodo.ai>
License: MIT
License-File: LICENSE
Keywords: agents,ai,code-review,mcp,qodo,sdk,testing
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Framework :: Pydantic :: 2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: aiofiles>=23.0
Requires-Dist: httpx>=0.25
Requires-Dist: mcp>=0.9.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Requires-Dist: types-aiofiles>=23.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Provides-Extra: tracing
Requires-Dist: opentelemetry-api>=1.20; extra == 'tracing'
Requires-Dist: opentelemetry-sdk>=1.20; extra == 'tracing'
Description-Content-Type: text/markdown

# Qodo Python SDK

[![PyPI version](https://img.shields.io/pypi/v/qodo-sdk.svg)](https://pypi.org/project/qodo-sdk/)
[![Python versions](https://img.shields.io/pypi/pyversions/qodo-sdk.svg)](https://pypi.org/project/qodo-sdk/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

Python SDK for building and running AI-powered agents on the [Qodo](https://qodo.ai) platform. The async-first Python counterpart to [`@qodo/sdk`](https://www.npmjs.com/package/@qodo/sdk).

## Installation

```bash
# Using uv (recommended)
uv add qodo-sdk

# Using pip
pip install qodo-sdk

# With OpenTelemetry tracing support
uv add "qodo-sdk[tracing]"
```

## Requirements

- Python 3.10+
- A Qodo API key (set as `QODO_API_KEY` environment variable or in `~/.qodo/auth.key`)

## Quick Start

```python
import asyncio
from qodo import QodoSDK, SdkEventType

async def main():
    async with QodoSDK(project_path="/path/to/project") as sdk:
        # Blocking run
        result = await sdk.prompt("Hello, world!")
        print(f"Output: {result.result.get('final_output')}")

        # Streaming
        async for event in sdk.stream_prompt("Write a greeting"):
            if event.type == SdkEventType.MESSAGE_DELTA:
                print(event.data.delta, end="", flush=True)
            elif event.type == SdkEventType.FINAL:
                print(f"\nDone! Success: {event.data.success}")

asyncio.run(main())
```

## Custom Agents

Define agents with Pydantic models for type-safe structured output:

```python
from pydantic import BaseModel, Field
from qodo import QodoSDK, sdk_agent, sdk_command

class ReviewOutput(BaseModel):
    issues: list[str] = Field(description="List of found issues")
    score: float = Field(description="Code quality score 0-10")
    summary: str = Field(description="Brief review summary")

agent = sdk_agent(
    instructions="You are a code reviewer.",
    commands={
        "review": sdk_command(
            name="review",
            description="Review code files",
            output=ReviewOutput,
            available_tools=["filesystem", "git"],
        )
    }
)

async with QodoSDK.from_agent(agent, project_path=".") as sdk:
    result = await sdk.run("review", args={"files": ["src/main.py"]})
    output = result.result.get("structured_output")
    print(f"Score: {output['score']}")
```

## Pipelines

Build multi-step workflows with the pipeline DSL:

```python
from qodo import QodoSDK, sdk_pipeline, run_pipeline

pipeline = (
    sdk_pipeline("code-review")
    .step("analyze", analyze_code)
    .step("report", generate_report)
    .build()
)

async with QodoSDK(project_path=".") as sdk:
    result = await run_pipeline(sdk, pipeline, {"repo": "."})
```

## Tool Approval Policies

Control tool execution with declarative policies:

```python
from qodo import QodoSDK, sdk_policy

policy = (
    sdk_policy()
    .approve("filesystem.*")       # Auto-approve filesystem reads
    .deny("shell.rm*")             # Block destructive commands
    .require_human("git.push*")    # Require human approval for pushes
    .build()
)

sdk = QodoSDK(project_path=".", tool_approval=policy.evaluate)
```

## Features

| Feature | Description |
|---------|-------------|
| **Async-first** | Built on `asyncio` with `async with` context manager |
| **Streaming** | Real-time event streaming with delta support |
| **Structured Output** | Pydantic v2 model validation for agent responses |
| **Pipelines** | Multi-step workflows with parallel execution |
| **Tool Middleware** | Pre/post hooks for tool call interception |
| **Policies** | Declarative tool approval with glob matching |
| **Artifacts** | Typed storage for pipeline intermediate results |
| **Tracing** | OpenTelemetry integration (optional `[tracing]` extra) |
| **Type Safety** | Full `py.typed` support with strict mypy |
| **Environment Isolation** | Multiple SDK instances via `contextvars` |

## More Examples

See the [examples/](examples/) directory for 14 runnable scripts covering all SDK features.

## Development

```bash
# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests
uv run pytest

# Lint & format
uv run ruff check src/qodo
uv run ruff format src/qodo

# Type check
uv run mypy src/qodo
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development guide.

## License

[MIT](LICENSE)
