Metadata-Version: 2.4
Name: kiva-sdk
Version: 0.3.0
Summary: A multi-agent orchestration SDK for building intelligent workflows
Project-URL: Homepage, https://github.com/Kiva-AI/Kiva-SDK
Project-URL: Documentation, https://github.com/Kiva-AI/Kiva-SDK#readme
Project-URL: Repository, https://github.com/Kiva-AI/Kiva-SDK
Project-URL: Issues, https://github.com/Kiva-AI/Kiva-SDK/issues
Author-email: Xingsandesu <admin@jintongshu.com>
Maintainer-email: Xingsandesu <admin@jintongshu.com>
License: MIT
License-File: LICENSE
Keywords: agents,ai,langchain,langgraph,llm,multi-agent,orchestration,workflow
Classifier: Development Status :: 3 - Alpha
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.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: langchain-openai>=1.1.7
Requires-Dist: langchain>=1.2.3
Requires-Dist: langgraph>=1.0.5
Requires-Dist: rich>=14.2.0
Description-Content-Type: text/markdown

# Kiva SDK

> ⚠️ **Important Notice**: This project is currently in a rapid iteration/experimental phase, and the provided API may undergo disruptive changes at any time.

A multi-agent orchestration SDK for building intelligent workflows

## Features

- **Three Workflow Patterns**: Router (simple), Supervisor (parallel), and Parliament (deliberative)
- **Automatic Complexity Analysis**: Intelligent workflow selection based on task complexity
- **Parallel Agent Instances**: Spawn multiple instances of the same agent for parallel subtask execution
- **Modular Architecture**: AgentRouter for organizing agents across multiple files
- **Streaming Events**: Real-time execution monitoring with structured events
- **Rich Console Output**: Beautiful terminal visualization (optional)
- **Error Recovery**: Built-in error handling with recovery suggestions
- **Flexible API Levels**: High-level client, mid-level console, and low-level streaming

## Installation

```bash
uv add kiva-sdk
```

## Quick Start

### High-Level API (Simplest)

```python
from kiva import Kiva

kiva = Kiva(
    base_url="https://api.openai.com/v1",
    api_key="your-api-key",
    model="gpt-4o",
)

# Single-tool agent using decorator
@kiva.agent("weather", "Gets weather information")
def get_weather(city: str) -> str:
    """Get current weather for a city."""
    return f"Sunny, 25°C in {city}"

# Multi-tool agent using class decorator
@kiva.agent("math", "Performs calculations")
class MathTools:
    def add(self, a: int, b: int) -> int:
        """Add two numbers."""
        return a + b
    
    def multiply(self, a: int, b: int) -> int:
        """Multiply two numbers."""
        return a * b

# Run with rich console output
kiva.run("What's the weather in Tokyo? Also calculate 15 * 8")
```

### Modular Application with AgentRouter

For larger applications, use `AgentRouter` to organize agents across multiple files:

```python
# agents/weather.py
from kiva import AgentRouter

router = AgentRouter(prefix="weather")

@router.agent("forecast", "Gets weather forecasts")
def get_forecast(city: str) -> str:
    """Get weather forecast for a city."""
    return f"Sunny, 25°C in {city}"
```

```python
# agents/math.py
from kiva import AgentRouter

router = AgentRouter(prefix="math")

@router.agent("calculator", "Performs calculations")
class Calculator:
    def add(self, a: int, b: int) -> int:
        """Add two numbers."""
        return a + b
```

```python
# main.py
from kiva import Kiva
from agents.weather import router as weather_router
from agents.math import router as math_router

kiva = Kiva(base_url="...", api_key="...", model="gpt-4o")

kiva.include_router(weather_router)
kiva.include_router(math_router)

kiva.run("What's the weather in Tokyo? Calculate 15 * 8")
```

See [AgentRouter Documentation](docs/agent-router.md) for more details.

### Mid-Level API (Async with Console)

```python
import asyncio
from kiva import run_with_console, create_agent, ChatOpenAI, tool

@tool
def search(query: str) -> str:
    """Search for information."""
    return f"Results for: {query}"

async def main():
    model = ChatOpenAI(model="gpt-4o", api_key="...")
    agent = create_agent(model=model, tools=[search])
    agent.name = "search_agent"
    agent.description = "Searches for information"
    
    await run_with_console(
        prompt="Search for Python tutorials",
        agents=[agent],
        base_url="https://api.openai.com/v1",
        api_key="your-api-key",
        model_name="gpt-4o",
    )

asyncio.run(main())
```

### Low-Level API (Full Control)

```python
import asyncio
from kiva import run, create_agent, ChatOpenAI, tool

@tool
def calculate(expr: str) -> str:
    """Evaluate a math expression."""
    return str(eval(expr))

async def main():
    model = ChatOpenAI(model="gpt-4o", api_key="...")
    agent = create_agent(model=model, tools=[calculate])
    agent.name = "calculator"
    agent.description = "Performs calculations"
    
    async for event in run(
        prompt="Calculate 100 / 4",
        agents=[agent],
        base_url="https://api.openai.com/v1",
        api_key="your-api-key",
        model_name="gpt-4o",
    ):
        match event.type:
            case "token":
                print(event.data["content"], end="", flush=True)
            case "workflow_selected":
                print(f"\nWorkflow: {event.data['workflow']}")
            case "agent_start":
                print(f"\nAgent started: {event.data.get('agent_id')}")
            case "agent_end":
                print(f"\nAgent finished")
            case "final_result":
                print(f"\n\nResult: {event.data['result']}")

asyncio.run(main())
```

## Workflow Patterns

### Router Workflow
Routes tasks to a single most appropriate agent. Best for simple, single-domain queries.

### Supervisor Workflow
Coordinates multiple agents executing in parallel. Supports spawning multiple instances of the same agent for parallel subtask processing. Ideal for multi-faceted tasks that can be decomposed into independent subtasks.

### Parliament Workflow
Implements iterative deliberation with conflict resolution. Designed for complex reasoning tasks requiring consensus or validation.

## Parallel Agent Instances

Kiva can spawn multiple instances of the same agent definition for parallel execution:

```python
# The planner automatically decides when to use parallel instances
# For example, this task might spawn 3 instances of a search agent:
kiva.run("Search for information about AI, blockchain, and quantum computing")
```

Each instance has:
- Isolated context/scratchpad
- Independent execution
- Results aggregated automatically

See [Parallel Instances Documentation](docs/parallel-instances.md) for details.

## Event Types

| Event | Description |
|-------|-------------|
| `token` | Streaming token from LLM |
| `workflow_selected` | Workflow and complexity determined |
| `parallel_start` | Parallel agent execution started |
| `agent_start` | Individual agent started |
| `agent_end` | Individual agent completed |
| `parallel_complete` | All parallel agents finished |
| `instance_spawn` | Agent instance spawned |
| `instance_complete` | Agent instance finished |
| `final_result` | Final synthesized result |
| `error` | Error occurred |

## Configuration

```python
async for event in run(
    prompt="Your task",
    agents=agents,
    model_name="gpt-4o",           # Lead agent model
    api_key="...",                  # API key
    base_url="...",                 # API base URL
    workflow_override="supervisor", # Force specific workflow
    max_iterations=10,              # Parliament max iterations
    max_parallel_agents=5,          # Max concurrent agents/instances
):
    ...
```

## Documentation

- [AgentRouter - Modular Applications](docs/agent-router.md)
- [Parallel Agent Instances](docs/parallel-instances.md)

## License

MIT License
