Metadata-Version: 2.4
Name: kora-agent
Version: 0.1.7.2
Summary: A lightweight Agent framework with extensible model providers
Project-URL: Homepage, https://github.com/xvshiting/kora
Project-URL: Repository, https://github.com/xvshiting/kora
Project-URL: Documentation, https://github.com/xvshiting/kora#readme
Project-URL: Issues, https://github.com/xvshiting/kora/issues
Author: xvshiting
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Requires-Dist: openai>=1.0.0
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: all
Requires-Dist: anthropic>=0.25.0; extra == 'all'
Requires-Dist: httpx[socks]>=0.25.0; extra == 'all'
Requires-Dist: kora-code>=0.1.0; extra == 'all'
Requires-Dist: mypy>=1.8.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'all'
Requires-Dist: pytest>=8.0.0; extra == 'all'
Requires-Dist: ruff>=0.3.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.25.0; extra == 'anthropic'
Provides-Extra: code
Requires-Dist: kora-code>=0.1.0; extra == 'code'
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Provides-Extra: network
Requires-Dist: httpx[socks]>=0.25.0; extra == 'network'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/branding/logo.png" alt="Kora" width="420">
</p>

<h3 align="center">A lightweight, layered Agent framework for Python</h3>

<p align="center">
  <a href="https://www.python.org/downloads/"><img alt="Python" src="https://img.shields.io/badge/python-3.12+-blue.svg"></a>
  <a href="https://opensource.org/licenses/MIT"><img alt="License" src="https://img.shields.io/badge/License-MIT-yellow.svg"></a>
  <img alt="Status" src="https://img.shields.io/badge/status-alpha-orange.svg">
</p>

---

**Kora** is a lightweight Python framework for building AI agents. Use it as a **Python SDK** to integrate agents into your applications, or launch the **Kora Code** CLI for an interactive AI coding partner.

```python
from kora import Agent, tool
from kora.providers import get_provider_registry

@tool
def calculate(expression: str) -> str:
    """Evaluate a math expression."""
    return str(eval(expression, {"__builtins__": {}}, {}))

model = get_provider_registry().get_model("deepseek", "deepseek-v4-flash")
agent = Agent(name="assistant", tools=[calculate], model=model)

result = agent.run_sync("What is 3 + 5?")
print(result)  # The model calls calculate(3+5) and responds with the answer
```

---

## Installation

```bash
# Kora SDK — integrate agents into your Python applications
pip install kora-agent

# Kora Code — interactive AI coding assistant (CLI)
pip install kora-agent kora-code
```

**Requires Python 3.12+.** Zero required runtime dependencies.

---

## Features

- **Minimal API.** `Agent`, `Session`, `@tool`, and you're done.
- **26 built-in model providers.** OpenAI, Anthropic, DeepSeek, DashScope, and more — one registry, one API.
- **8 core tools out of the box.** Filesystem, shell, Python sandbox, and user interaction — all workspace-scoped.
- **Security by code, not by prompt.** SSRF protection, command filtering, import restrictions, and workspace isolation are enforced in implementation.
- **Observable by default.** Every run emits structured events (`RunStarted`, `ToolExecuted`, `RunCompleted`, ...) for streaming and debugging.

---

## Quick Start

### SDK — Build agents in Python

```python
from kora import Agent, tool
from kora.providers import get_provider_registry
from kora.tools import get_core_tools
import asyncio

@tool
def echo(message: str) -> str:
    """Echo back a message."""
    return f"Echo: {message}"

model = get_provider_registry().get_model("deepseek", "deepseek-v4-flash")

agent = Agent(
    name="assistant",
    system_prompt="You are a helpful assistant.",
    tools=[echo, *get_core_tools(".")],
    model=model,
)

async def main():
    session = agent.open_session()
    result = await session.send("What files are in this directory?")
    print(result)

asyncio.run(main())
```

> 📖 **[Kora Agent SDK Tutorials](docs/tutorials/agent/01-quickstart.md)** — 8 chapters covering agents, tools, providers, sessions, events, and more.

### CLI — Launch an AI coding assistant

```bash
# Interactive REPL
kora code

# One-shot task
kora code "Refactor src/main.py to use async/await"

# Custom agent
kora run --agent /path/to/AGENT.md
```

> 📖 **[Kora Code CLI Tutorials](docs/tutorials/code/01-quickstart.md)** — 5 chapters on commands, modes, customization, and best practices.

---

## Documentation

| Resource | Description |
|----------|-------------|
| **[Getting Started](docs/getting-started.md)** | Setup and your first agent |
| **[Tools Guide](docs/tools.md)** | All built-in tools with parameters |
| **[API Reference](docs/api.md)** | Complete API reference |
| **[Examples](examples/)** | Runnable demo scripts |
| **📖 [SDK Tutorials](docs/tutorials/agent/01-quickstart.md)** | Step-by-step Python SDK guide (8 chapters) |
| **📖 [CLI Tutorials](docs/tutorials/code/01-quickstart.md)** | Step-by-step Kora Code guide (5 chapters) |
| **[Architecture Decisions](docs/decisions/)** | ADR records for architectural boundaries |
| **[Current State](docs/CURRENT.md)** | What is implemented today |

---

## Model Providers

Kora ships with **26 built-in providers** covering 300+ models. Set the corresponding environment variable and go:

| Provider ID | Example models | API key env |
|-------------|----------------|-------------|
| `openai` | `gpt-4o`, `gpt-4-turbo`, `gpt-3.5-turbo` | `OPENAI_API_KEY` |
| `anthropic` | `claude-3-5-sonnet-20241022`, `claude-3-opus-20240229` | `ANTHROPIC_API_KEY` |
| `agnes` | `agnes-2.0-flash` | `AGNES_API_KEY` |
| `dashscope` | `qwen-max`, `qwen-plus`, `qwen-turbo` | `DASHSCOPE_API_KEY` |
| `jdcloud` | `glm-5`, `glm-4` | `JDCLOUD_API_KEY` |
| `deepseek` | `deepseek-chat`, `deepseek-reasoner`, `deepseek-v4-flash` | `DEEPSEEK_API_KEY` |
| `deepseek-anthropic` | `deepseek-v4-flash`, `deepseek-v4-pro` (via Anthropic API) | `DEEPSEEK_API_KEY` |
| `moonshot` | `moonshot-v1-8k`, `moonshot-v1-32k`, `moonshot-v1-128k` | `MOONSHOT_API_KEY` |
| `openrouter` | `anthropic/claude-3.5-sonnet`, `openai/gpt-4o` | `OPENROUTER_API_KEY` |
| `ollama` | `llama3`, `mistral`, `qwen2` | local (no key) |

[Full provider list →](docs/tutorials/agent/04-providers.md)

Custom provider? Register one in 5 lines:

```python
from kora.providers import ProviderSpec, ModelSpec, get_provider_registry

registry = get_provider_registry()
registry.register(ProviderSpec(
    id="my-provider", name="My Provider",
    base_url="https://api.example.com/v1", api="openai-completions",
    api_key="${MY_API_KEY}",
    models=(ModelSpec(id="my-model", name="My Model", tool_calling=True),),
))
```

---

## Built-in Tools

Use `get_core_tools(workspace)` to get the **8 essential tools** for a coding agent:

| Tool | Capability |
|------|-----------|
| `list_files` | Browse directories (ls, find, tree) |
| `search_text` | Search file contents (grep, rg) |
| `read_file` | View files with line ranges (cat, head, tail) |
| `write_file` | Create or overwrite files |
| `apply_patch` | Apply targeted text patches |
| `run_shell` | Execute shell commands (filtered) |
| `execute_python` | Run Python in a sandbox |
| `request_interaction` | Ask the user for input |

[Full tool reference →](docs/tools.md)

---

## Architecture

```
Interface → Host → Runtime → Kernel
```

| Layer | Responsibility |
|-------|---------------|
| **Kernel** | Synchronous model-tool loop. No knowledge of agents, sessions, or users. |
| **Runtime** | Async Agent/Session/Run lifecycle. Event emission, context management. |
| **Host** | Persistence, identity, permissions, instruction composition. |

Each layer depends only on the layer inside it. The Kernel is fully testable with fake models — no network required.

---

## Contributing

Kora is intentionally small. Before making a change, read [`CLAUDE.md`](CLAUDE.md) and the [ADR records](docs/decisions/).

1. Identify which architectural layer owns the change.
2. Prefer the smallest complete change; add tests with behavior changes.
3. Do not cross established layer boundaries.

```bash
pip install -e ".[dev]"   # editable install with dev tooling
pytest                    # run tests
ruff check src/kora       # lint
```

## License

MIT
