soveren-agent-platform 0.2.0__tar.gz

soveren_agent_platform-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.12"
+          - "3.13"
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v8
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --group dev --locked
+
+      - name: Check lockfile
+        run: uv lock --check
+
+      - name: Lint
+        run: uv run ruff check src tests
+
+      - name: Type check
+        run: uv run mypy
+
+      - name: Test
+        run: uv run pytest
+
+      - name: Build distributions
+        run: uv build

soveren_agent_platform-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/soveren-agent-platform
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v8.3.1
+        with:
+          enable-cache: true
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

soveren_agent_platform-0.2.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+.pytest_cache/
+__pycache__/
+*.py[cod]
+*.sqlite
+*.sqlite3
+*.db
+*.db-shm
+*.db-wal
+.DS_Store
+

soveren_agent_platform-0.2.0/AGENTS.md

@@ -0,0 +1,83 @@
+# AGENTS.md
+
+Guidance for coding agents working in this repository.
+
+## Read First
+
+Before changing architecture or module boundaries, read:
+
+- `docs/ARCHITECTURE.md` — current runtime architecture, module ownership,
+  event/session flows, extension rules, and package naming notes.
+- `docs/API.md` — consumer-facing integration API, bootstrap contract, runtime
+  composition, and packaging/deployment dependency guidance.
+- `docs/PORTS.md` — queue/store ports, adapter semantics, and persistence
+  boundaries.
+- `docs/EXTRACTION_PLAN.md` — extraction history and rollout context.
+
+This repo is the reusable runtime core. Keep product prompts, business tools,
+private schema, product copy, and app-specific workflows in application repos.
+
+## Commands
+
+Run from the repo root:
+
+```bash
+uv sync --group dev
+uv run ruff check src tests
+uv run mypy
+uv run pytest
+```
+
+For a focused test:
+
+```bash
+uv run pytest tests/test_session_mailbox.py
+uv run pytest tests/test_session_mailbox.py::test_mailbox_drain_uses_session_and_mailbox_ports
+```
+
+Before considering a code change done, run:
+
+```bash
+uv run ruff check src tests && uv run mypy && uv run pytest
+```
+
+## Python Style
+
+- Target Python is `>=3.12`.
+- Use type annotations on public functions, protocols, dataclasses, worker
+  entrypoints, and adapter methods.
+- Prefer `dataclass(slots=True)` or `dataclass(frozen=True, slots=True)` for
+  typed value objects.
+- Use `Protocol` for runtime ports.
+- Avoid untyped dictionaries at module boundaries. If payloads must be dynamic,
+  keep them at the edge and convert to typed objects quickly.
+- Do not silence mypy unless there is a precise reason and a narrow comment.
+- Keep imports sorted by `ruff`.
+
+## Engineering Rules
+
+- Preserve the architecture documented in `docs/ARCHITECTURE.md`.
+- Preserve port semantics documented in `docs/PORTS.md`.
+- Do not introduce generic CRUD repositories.
+- Do not split atomic runtime boundaries such as batch routing, action dispatch,
+  queue lease/retry, or session mailbox delivery.
+- Do not make routers depend directly on Codex, Claude, tmux, or app-server
+  native APIs; route through generalized session snapshots and platform ports.
+- Do not add app-owned tables or product seed data to platform migrations.
+- If a new architectural boundary appears, update `docs/ARCHITECTURE.md` and
+  `docs/PORTS.md` in the same change.
+
+## Testing Expectations
+
+Add or update tests when changing:
+
+- queue lease/retry/idempotency behavior
+- batching decisions or `route_batch`
+- action dispatch and approval transitions
+- mailbox/session status transitions
+- snapshot/routing/indexing behavior
+- migration/schema compatibility
+- public composition APIs in `AgentPlatformApp`
+
+Prefer focused unit tests around ports and fake adapters. Add integration-style
+SQLite tests for transaction boundaries.

soveren_agent_platform-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Soveren
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

soveren_agent_platform-0.2.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: soveren-agent-platform
+Version: 0.2.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="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 is the extraction target for the shared runtime currently
+implemented inside `poruchen`. It is intentionally separate from both
+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 first usable slice in this repo contains:
+
+- SQLite connection setup
+- 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 due-job leasing and app-provided handlers
+- Telegram interface module that normalizes Telegram ingress into queue events
+- optional python-telegram-bot adapter for inbound normalization and outbound sending
+- optional python-telegram-bot runtime builder with message and callback hooks
+- LLM backend contracts and reusable OpenAI-compatible/session-backed backends
+- agent run persistence helpers
+- 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 and tmux execution session backends
+- reusable Codex app-server execution session backend
+- 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
+- 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 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the current architecture.
+See [docs/API.md](docs/API.md) for the consumer integration API and quick start.
+See [docs/EXTRACTION_PLAN.md](docs/EXTRACTION_PLAN.md) for the rollout plan.
+See [docs/PORTS.md](docs/PORTS.md) for the queue/store abstraction strategy.
+
+## 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
+`soveren_agent_platform.storage.bootstrap_platform_storage(db_path)` themselves and pass
+`bootstrap_storage=False`.
+
+## Local Development
+
+```bash
+uv sync --group dev
+uv run ruff check src tests
+uv run mypy
+uv run pytest
+```

soveren_agent_platform-0.2.0/README.md

@@ -0,0 +1,97 @@
+<p align="center">
+  <img src="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 is the extraction target for the shared runtime currently
+implemented inside `poruchen`. It is intentionally separate from both
+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 first usable slice in this repo contains:
+
+- SQLite connection setup
+- 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 due-job leasing and app-provided handlers
+- Telegram interface module that normalizes Telegram ingress into queue events
+- optional python-telegram-bot adapter for inbound normalization and outbound sending
+- optional python-telegram-bot runtime builder with message and callback hooks
+- LLM backend contracts and reusable OpenAI-compatible/session-backed backends
+- agent run persistence helpers
+- 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 and tmux execution session backends
+- reusable Codex app-server execution session backend
+- 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
+- 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 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the current architecture.
+See [docs/API.md](docs/API.md) for the consumer integration API and quick start.
+See [docs/EXTRACTION_PLAN.md](docs/EXTRACTION_PLAN.md) for the rollout plan.
+See [docs/PORTS.md](docs/PORTS.md) for the queue/store abstraction strategy.
+
+## 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
+`soveren_agent_platform.storage.bootstrap_platform_storage(db_path)` themselves and pass
+`bootstrap_storage=False`.
+
+## Local Development
+
+```bash
+uv sync --group dev
+uv run ruff check src tests
+uv run mypy
+uv run pytest
+```