Metadata-Version: 2.4
Name: superpos-agent-core
Version: 0.1.0
Summary: Shared runtime for Superpos slim agents (Telegram bot, Superpos poller, worktree manager, telegram streamer).
Author: Superpos
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: python-telegram-bot>=21.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"

# superpos-agent-core

Shared runtime for the Superpos "slim agent" family — the part that is identical across Claude, Codex, Gemini, Qwen, and any future LLM-CLI-backed agent.

## What lives here

- `Executor` protocol + `ExecutionRequest` — the contract every agent implementation must satisfy.
- `SuperposClient` — REST client for the Superpos backend (tasks, persona, agent lifecycle).
- `run_superpos_poller` — daemon that polls Superpos for tasks and enqueues them on an `Executor`.
- `TelegramGateway` + `TelegramStreamer` + `build_telegram_app` / `run_telegram_bot` — Telegram I/O with backpressure, flood-ban handling, message streaming.
- `WorktreeManager` helpers — per-branch isolation via `git worktree`.
- `SessionStore`, `RecentTasksLog`, `RuntimeConfig` — persistence and runtime knobs.
- `redact()` — strip known secret patterns from outbound text.
- `run_agent()` — orchestrator that wires everything together given a concrete `Executor` factory.

## What does NOT live here

- Per-agent executor implementations (`ClaudeExecutor`, `CodexExecutor`, `GeminiExecutor`, …) — they live in each agent's own repo and depend on this package.
- LLM SDK / CLI installation — each agent's Dockerfile is responsible.
- Per-agent config (model lists, auth env vars) — subclassed from `BaseConfig`.

## Using it

```python
from superpos_agent_core import run_agent, BaseConfig, Executor

class MyAgentConfig(BaseConfig):
    my_api_key: str = ""

class MyExecutor:
    # implements superpos_agent_core.Executor
    ...

if __name__ == "__main__":
    import asyncio
    config = MyAgentConfig.from_env(extra={"my_api_key": "MY_API_KEY"})
    asyncio.run(run_agent(
        config=config,
        executor_factory=lambda cfg, runtime, superpos, gateway, persona:
            MyExecutor(cfg, runtime, superpos, gateway, persona=persona),
    ))
```

See `Slim-Agent-Gemini/` for a complete working example.
