Metadata-Version: 2.4
Name: soveren-agent-platform
Version: 0.7.0
Summary: Reusable runtime core for durable agent applications.
Project-URL: Homepage, https://github.com/neureca/soveren-agent-platform
Project-URL: Repository, https://github.com/neureca/soveren-agent-platform
Project-URL: Issues, https://github.com/neureca/soveren-agent-platform/issues
Author: Soveren
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: pydantic>=2
Requires-Dist: python-dateutil>=2.8
Provides-Extra: telegram
Requires-Dist: python-telegram-bot>=21; extra == 'telegram'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/neureca/soveren-agent-platform/v0.7.0/docs/assets/soveren-logo.svg" width="96" height="96" alt="Soveren logo" />
</p>

<h1 align="center">Soveren Agent Platform</h1>

<p align="center">
  Reusable runtime core for durable agent applications.
</p>

This repository contains the reusable runtime core shared by agent
applications. It is intentionally separate from application repositories:

- `soveren-agent-platform` owns reusable mechanics: durable queueing, run tracking,
  decision/action framework, batching, scheduler, sessions, integration
  contracts, and bundled SQLite adapters for the default embedded runtime.
- `poruchen` owns private product behavior: prompts, ClickUp tools, approval
  copy, policies, and app-specific schema.
- `pulsell-agent` owns Pulsell-specific media, transcription, vision, task, and
  workflow behavior.

The current package contains:

- asynchronous SQLite adapters with internal serialized transactions
- durable queue port with a SQLite adapter
- layered migration runner with platform/app migration providers
- platform migrations for `event_queue` and `agent_runs`
- durable queue API
- inbound batching module with SQLite state and flush wakeups
- agent worker module that consumes queue events and calls app-provided agents
- cron module with atomic due-event publication and conversation-scoped
  cancellation
- Telegram interface module that normalizes Telegram ingress into queue events
- optional Telegram adapter for inbound normalization and outbound sending
- high-level Telegram agent bootstrap for default polling deployments
- optional Telegram polling runtime builder with message and callback hooks
- LLM backend contracts and reusable OpenAI-compatible/session-backed backends
- agent run persistence helpers
- durable planner decision reuse across dispatch retries
- optional one-accepted-decision receipts across model and prompt changes
- rich planner context builder for batches, sessions, mailbox, actions,
  outbound, cron, and routing metadata
- optional app-neutral prompt formatter for rich planner context
- planner envelope that injects session routing and rich context into LLM
  requests
- execution session mailbox for prompts queued behind busy sessions
- persistent execution-session events, snapshots, and deterministic routing
- reusable stub execution backend and a low-level tmux command-session utility
  that requires an explicit completion marker
- reusable Codex app-server execution session backend
- Docker-isolated Codex runtime for externally triggered work, with coarse resource profiles,
  persistent idle-stop lifecycle, and bounded egress
- packaged Codex sandbox image, per-conversation networks, and enforced shared egress boundary
- shared, tenant-isolated HTTP credential broker that keeps provider keys out of conversation sandboxes
- explicit app-neutral memory store and access-scoped Codex dynamic tools
- automatic conversation-scoped message history with FTS search, neighboring
  context, bounded searchable-history pruning, and read-only Codex dynamic tools
- Codex app-server dynamic tool contracts, registry, and fail-closed JSON-RPC
  tool-call handling
- session backend registry for wiring reusable and custom backends
- platform SQLite migration and schema compatibility checks
- generic actions/approvals lifecycle with app-registered executors
- generic outbound channel queue with app-registered senders
- explicit audited reconciliation for uncertain action and outbound effects
- decision dispatcher that maps typed decisions to outbound, actions, session
  mailbox, or cron side effects
- planner-dispatch helper for fake-tested context to side-effect pipelines
- runtime supervisor and `AgentPlatformApp` composition helper for standard
  platform workers

See [Architecture](https://github.com/neureca/soveren-agent-platform/blob/v0.7.0/docs/ARCHITECTURE.md)
for the current architecture.
See [Integration API](https://github.com/neureca/soveren-agent-platform/blob/v0.7.0/docs/API.md)
for the consumer integration API and quick start.
See [Consuming App Guide](https://github.com/neureca/soveren-agent-platform/blob/v0.7.0/docs/CONSUMING_APP.md)
for a practical consuming-app
guide covering package dependency, Telegram wiring, and app-owned tools such as
ClickUp.
See [Ports](https://github.com/neureca/soveren-agent-platform/blob/v0.7.0/docs/PORTS.md)
for the queue/store abstraction strategy.
See [Docker Sandbox Deployment](https://github.com/neureca/soveren-agent-platform/blob/v0.7.0/deploy/sandbox/README.md)
for the Docker sandbox
deployment path.

## Installation

```bash
uv add "soveren-agent-platform>=0.7,<0.8"
```

Use `soveren-agent-platform[telegram]>=0.7,<0.8` when the app uses the bundled
Telegram adapter.

## Consumer Quick Start

```python
from pathlib import Path

from soveren_agent_platform.agent import AgentEvent, AgentHandler
from soveren_agent_platform.app_api import AgentPlatformApp


class AppAgentHandler(AgentHandler):
    async def handle(self, event: AgentEvent) -> None:
        ...


app = (
    AgentPlatformApp(db_path=Path("data/app.db"))
    .use_batching()
    .use_agent(handler=AppAgentHandler())
)
```

`AgentPlatformApp` applies and validates platform migrations before workers
start. Apps with a separate migration pipeline can call
`await soveren_agent_platform.storage.bootstrap_platform_storage(db_path)` themselves and pass
`bootstrap_storage=False`.

Externally triggered Codex workloads must use
`AgentPlatformApp.configure_sandboxed_codex(...)`. Configure it once during
application bootstrap and pass the returned runtime to `PlannerRuntime`. The
`AgentPlatformApp` then owns conversation backend selection, registration,
isolation, durable sessions, mailbox delivery, and shutdown. Provider
credentials are resolved from trusted `tenant_id`; applications do not create
Docker managers or Codex backend registries.

## Local Development

```bash
uv sync --group dev
uv run ruff check src tests scripts
uv run mypy
uv run pytest
```

## Release

Before the first release, run `Bootstrap Runtime Packages` from `main`. GitHub creates
new GHCR packages as private and does not expose a package-visibility API. After the
workflow creates all three `bootstrap` tags, set each package to Public in the
organization package settings and rerun the workflow. Its anonymous pulls must pass.

1. Open a pull request into `main`; direct pushes are blocked.
2. Wait for Python 3.12, Python 3.13, sandbox smoke, and CodeQL checks.
3. Merge with squash or rebase after all conversations are resolved.
4. Confirm the three public `bootstrap` images remain anonymously pullable.
5. Create and push a tag matching the package version, for example `v0.7.0`.
6. Open the Publish workflow in GitHub Actions and approve the pending `pypi`
   deployment. PyPI authentication uses the configured trusted publisher, not
   a stored API token.

The `pypi` environment accepts only `v*` tags. The publish workflow additionally
checks that the tag version matches `pyproject.toml` and that the tagged commit
belongs to `main`. It fails before release validation unless all runtime package
namespaces have already passed the anonymous bootstrap pull.
