qodo-sdk 0.1.0

Qodo Python SDK for AI-powered agents

Qodo Python SDK

Python SDK for building and running AI-powered agents on the Qodo platform. The async-first Python counterpart to @qodo/sdk.

Installation

# 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

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:

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:

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:

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/ directory for 14 runnable scripts covering all SDK features.

Development

# 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 for the full development guide.

License

MIT