Metadata-Version: 2.4
Name: agentyoke
Version: 0.1.0
Summary: Тонкий harness-фреймворк для AI-агентов: сменный провайдер рантайма (API/Claude Code/Codex), middleware-pipeline и слой skills/MCP.
Project-URL: Homepage, https://github.com/mogilevtsevdmitry/agentyoke
Project-URL: Documentation, https://github.com/mogilevtsevdmitry/agentyoke/tree/main/docs
Author-email: Dmitry Mogilevtsev <mogilevtsev.dmitry@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agents,ai,claude,codex,harness,litellm,llm,mcp,opentelemetry,pydantic-ai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Requires-Dist: litellm>=1.40
Requires-Dist: opentelemetry-api>=1.25
Requires-Dist: opentelemetry-exporter-otlp>=1.25
Requires-Dist: opentelemetry-sdk>=1.25
Requires-Dist: pydantic-ai>=0.0.14
Requires-Dist: pydantic-settings>=2.3
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6.0
Provides-Extra: claude-code
Requires-Dist: claude-agent-sdk>=0.1; extra == 'claude-code'
Provides-Extra: codex
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# agentyoke

> Тонкий harness-фреймворк для AI-агентов: сменный провайдер рантайма
> (**API / Claude Code / Codex**), middleware-pipeline и слой skills/MCP.

**Один интерфейс — любой агентный рантайм.** *Yoke* (ярмо/упряжь) — это та самая
упряжь, что заставляет несколько волов тянуть в одну сторону. agentyoke делает
то же с разными агентными рантаймами и моделями: прикладной код агента не знает,
кто внутри — собственный цикл над LiteLLM, Claude Code или Codex.

> ✅ **Статус: 0.1.0 — рабочая реализация.** Конфиг, middleware-pipeline
> (logging / cost / rate-limit / guardrails / cache / retry), observability,
> загрузчик skills, `ApiProvider` (agentic-loop) и CLI-провайдеры реализованы и
> покрыты тестами (`ruff` + `mypy --strict` + `pytest`).

---

## Ключевая идея

1. **Гибрид: тонкое собственное ядро** — не монолитный фреймворк. Ядро владеет
   контрактами (`AgentProvider`, `AgentEvent`); Pydantic отвечает за конфиг и
   валидацию, а собственный agentic-loop ходит в модель через LiteLLM.
2. **Provider как сменный модуль на двух уровнях:**
   - *модель* — через **LiteLLM** (любой LLM за единым API);
   - *агентный рантайм* — через `AgentProvider` (свой цикл / Claude Code / Codex).
3. **CLI как провайдер** — Claude Code и Codex CLI за тем же интерфейсом, что и API.
4. **Middleware-pipeline** — логи, стоимость, лимиты, кеш, guardrails как
   композируемые кросс-срезы, а не код внутри ядра.
5. **Skills/SKILL.md + AGENTS.md + MCP** — три слоя инструкций и доступа.
6. **OpenTelemetry GenAI conventions** — наблюдаемость из коробки.

```mermaid
flowchart LR
    App["Агент-приложение<br/>(agents/&lt;name&gt;)"] --> MW["Middleware<br/>pipeline"]
    MW --> P{"AgentProvider"}
    P -->|api| API["ApiProvider<br/>(собственный цикл + LiteLLM)"]
    P -->|claude_code| CC["ClaudeCodeProvider<br/>(Claude Agent SDK / CLI)"]
    P -->|codex| CX["CodexProvider<br/>(Codex CLI / SDK)"]
    API --> M[("LLM через LiteLLM")]
    MW -.->|спаны/метрики| OTel["OpenTelemetry"]
```

## Установка

```bash
# из PyPI (после первого релиза: тег v0.1.0 публикует пакет через CI)
pip install agentyoke
# опциональные CLI-рантаймы:
pip install "agentyoke[claude-code]"
```

## Quick start

```bash
# для разработки — из исходников
uv venv --python 3.12
uv pip install -e ".[dev]"

# запуск примера агента (нужен ключ модели, напр. ANTHROPIC_API_KEY)
python -m agents.example.run
```

Высокоуровневый API — класс `Agent`: загружает конфиг, собирает провайдер и
middleware-цепочку, и отдаёт либо поток событий, либо агрегированный результат.

```python
from agentyoke import Agent, Message, ToolRegistry

tools = ToolRegistry()


@tools.register
def current_time() -> str:
    """Текущее время."""
    from datetime import UTC, datetime
    return datetime.now(UTC).isoformat()


agent = Agent.from_config("agents/example/config.yaml", tools=tools)

# Поток событий (TextDelta / ToolCallEvent / UsageEvent / ...):
async for event in agent.run_stream([Message(role="user", content="Который час?")]):
    print(event)

# Или агрегированный результат целиком:
result = await agent.run([Message(role="user", content="Который час?")])
print(result.text, result.usage)
```

Сменить рантайм — это поменять одну строку `provider:` в `config.yaml`
(`api` → `claude_code` → `codex`). Прикладной код не меняется.

> Если выбран `provider: api`, но `ANTHROPIC_API_KEY` не задан, агент прозрачно
> использует **локальную сессию Claude Code** (провайдер `claude_code`) — удобно
> для подписочного доступа без API-ключа. Отключается флагом
> `Agent(..., local_session_fallback=False)`.

## Документация

| Документ | О чём |
|---|---|
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Архитектурный обзор: два уровня провайдеров, ядро, потоки |
| [docs/PROVIDERS.md](docs/PROVIDERS.md) | Спека `AgentProvider`, `AgentEvent`, контракт каждого провайдера |
| [docs/MIDDLEWARE.md](docs/MIDDLEWARE.md) | Middleware-pipeline, встроенные middleware, 3 уровня политик |
| [docs/SKILLS.md](docs/SKILLS.md) | Три слоя: skills (SKILL.md) / AGENTS.md / MCP |
| [docs/OBSERVABILITY.md](docs/OBSERVABILITY.md) | OpenTelemetry, GenAI semantic conventions |
| [docs/ROADMAP.md](docs/ROADMAP.md) | Этапы 0–4 с оценками сроков |
| [docs/REFERENCES.md](docs/REFERENCES.md) | Источники: Omnigent, Pydantic AI, LiteLLM и др. |

## Структура репозитория

```
agentyoke/
├── src/agentyoke/        # ядро (тонкое): провайдеры, middleware, skills, observability
├── agents/               # агенты-приложения (каждый — свой config.yaml)
├── docs/                 # спецификации (источник истины)
├── CLAUDE.md / AGENTS.md # инструкции для агентных инструментов
└── pyproject.toml
```

---

## English summary

**agentyoke** is a *thin* harness framework for AI agents. The core idea is a
**slim own core** rather than a monolithic framework: the core owns the
contracts, while its own agentic loop talks to models through LiteLLM. Providers
are swappable on two levels: the **model** (via LiteLLM) and
the **agent runtime** (`AgentProvider`: own loop, Claude Code, or Codex — *"CLI
as a provider"*). Cross-cutting concerns (logging, cost tracking, rate limits,
caching, guardrails) live in a composable **middleware pipeline**. Instructions
and access come in three layers — **Skills (SKILL.md) + AGENTS.md + MCP** — and
observability follows **OpenTelemetry GenAI semantic conventions**.

Switching the runtime is a one-line `provider:` change in `config.yaml`; the
application agent code stays the same. See `docs/` for full specifications.

> **Status: 0.1.0** — the core is implemented and tested: config loading, the
> middleware pipeline, observability, the skills loader, the `ApiProvider`
> agentic loop, and the CLI providers.

## License

MIT.
