agentexec 0.2.0rc1__tar.gz → 0.2.0rc2__tar.gz

agentexec-0.2.0rc2/.python-version

@@ -0,0 +1 @@
+3.12

{agentexec-0.2.0rc1 → agentexec-0.2.0rc2}/CHANGELOG.md

@@ -1,5 +1,118 @@
 # Changelog
 
+## v0.2.0rc2
+
+Second release candidate for 0.2.0. Completes the async migration and
+stabilizes the worker pool architecture.
+
+### Breaking Changes
+
+**Fully async database layer**
+- `configure_engine()` and `get_session()` now require an async SQLAlchemy engine (`AsyncEngine`) and return `AsyncSession`
+- Database URLs must use async drivers (e.g. `sqlite+aiosqlite://`, `postgresql+asyncpg://`)
+- `sqlalchemy[asyncio]` is now a core dependency; `aiosqlite` added as dev dependency
+
+**Async activity query API**
+- `activity.list()`, `activity.detail()`, and `activity.count_active()` are now async and accept `AsyncSession`
+- Activity handlers are now async (`async def __call__`)
+
+**Removed `session` parameter from activity mutations**
+- `activity.create()`, `activity.update()`, `activity.complete()`, and `activity.error()` no longer accept a `session` parameter — the handler owns its own session lifecycle
+
+**Queue priority parameter**
+- `BaseQueueBackend.push()` signature changed from `high_priority: bool` to `priority: Priority | None`
+- Affects Redis, Kafka, and any custom queue backend implementations
+
+### New Features
+
+**CLI entrypoint**
+- New `agentexec` CLI command via `[project.scripts]`
+
+**Activity model `create()` classmethod**
+- `Activity.create()` encapsulates record + initial log entry creation in one async call
+
+**Async engine disposal**
+- `dispose_engine()` ensures the async engine's background threads exit cleanly on shutdown
+
+### Architecture Changes
+
+**Worker pool refactor**
+- Workers now use the `spawn` multiprocessing start method with explicit context — no inherited state
+- `StateEvent` replaced with stdlib `multiprocessing.Event` — removes dependency on the state backend for shutdown coordination
+- Event handling and scheduling extracted into `_EventHandler` and `_Scheduler` classes
+- Worker processes are now daemonic with `SIGINT` ignored — clean shutdown driven by the event
+- `pool.start()` handles `CancelledError` directly for Ctrl+C shutdown
+
+**Logging overhaul**
+- Removed `worker/logging.py` and `core/logging.py` — all modules use stdlib `logging.getLogger(__name__)`
+- Spawned workers bootstrap a `StreamHandler` on the root logger so logs reach stderr
+- Pool messages use `logger.info`/`logger.error` instead of `print()`
+
+### Bug Fixes
+
+- Fixed crash when worker receives a task for an unregistered task name (now logs error and skips)
+- Failed tasks now log full tracebacks via `logger.exception` instead of `logger.error`
+- Kafka consumer handles `None` message values without crashing
+- `ActivityUpdated.status` is now `Status` enum instead of raw string
+- `raise e` instead of bare `raise` in task execution for clearer tracebacks
+
+### Improvements
+
+- Dependency groups use PEP 735 `[dependency-groups]` instead of `[tool.uv]`
+- Ruff line-length increased to 110
+- Removed verbose docstring examples and redundant comments throughout activity models
+- `selectinload` for eager loading of activity logs in `get_by_agent_id`
+- Redis backend adds `type: ignore` annotations for redis-py async stubs
+
+## v0.2.0rc1
+
+First release candidate for 0.2.0. Major refactor of the backend, queue,
+activity, and worker systems.
+
+### Breaking Changes
+
+**Backend module restructure**
+- `agentexec.state.redis_backend` renamed to `agentexec.state.redis` — update `AGENTEXEC_STATE_BACKEND` if set explicitly
+- `AGENTEXEC_QUEUE_NAME` renamed to `AGENTEXEC_QUEUE_PREFIX` (old name still accepted as alias)
+
+**Async activity API**
+- Activity functions are now async: `await ax.activity.create(...)`, `await ax.activity.update(...)`, etc.
+
+**Task context serialization**
+- `Task.context` is now `Mapping[str, Any]` (raw dict), not a typed BaseModel — hydration happens at execution time
+- `Task.create()` is now async
+
+**Removed APIs**
+- `set_global_session`/`get_global_session`/`remove_global_session` — use `configure_engine`/`get_session`
+- `state.backend.publish`/`subscribe` (pubsub), `index_add`/`index_range`/`index_remove`, `clear`, `configure`
+
+### New Features
+
+**Partitioned Redis queues**
+- Tasks with `lock_key` route to dedicated partition queues with per-partition locking and SCAN-based fair dequeue
+
+**Activity handler pattern**
+- Pluggable persistence via `PostgresHandler` (default) and `IPCHandler` (worker processes)
+
+**Task retry**
+- Failed tasks requeue as high priority with `AGENTEXEC_MAX_TASK_RETRIES` (default 3)
+
+**Kafka backend (experimental)**
+- `pip install agentexec[kafka]` for queue and schedule via Kafka
+
+**Typed worker IPC**
+- `TaskFailed`, `LogEntry`, `ActivityUpdated` messages over `multiprocessing.Queue`
+
+**Schedule composite keys**
+- `{task_name}:{cron}:{context_hash}` for unique schedule identity
+
+### Improvements
+
+- Class-based backend architecture with ABCs (`BaseStateBackend`, `BaseQueueBackend`, `BaseScheduleBackend`)
+- `Task` is pure data, `TaskDefinition` owns behavior
+- Session management via `configure_engine`/`get_session` (Pool owns the engine)
+- Status enum extracted to `activity/status.py` (no SQLAlchemy dependency)
+
 ## v0.1.7
 
 ### New Features

{agentexec-0.2.0rc1 → agentexec-0.2.0rc2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentexec
-Version: 0.2.0rc1
+Version: 0.2.0rc2
 Summary: Production-ready orchestration for OpenAI Agents with Redis-backed coordination, activity tracking, and workflow management
 Project-URL: Homepage, https://github.com/Agent-CI/agentexec
 Project-URL: Documentation, https://github.com/Agent-CI/agentexec#readme
@@ -21,7 +21,7 @@ Requires-Dist: openai-agents>=0.1.0
 Requires-Dist: pydantic-settings>=2.5.0
 Requires-Dist: pydantic>=2.12.0
 Requires-Dist: redis>=7.0.1
-Requires-Dist: sqlalchemy>=2.0.44
+Requires-Dist: sqlalchemy[asyncio]>=2.0.44
 Provides-Extra: kafka
 Requires-Dist: aiokafka>=0.11.0; extra == 'kafka'
 Description-Content-Type: text/markdown

agentexec-0.2.0rc2/RELEASE.md

@@ -0,0 +1,91 @@
+# Release Process
+
+This document describes how to publish a new release of agentexec.
+
+## Overview
+
+Creating a **GitHub Release** triggers three publish workflows automatically:
+
+| Workflow | Target | Secret Required |
+|---|---|---|
+| `publish.yml` | PyPI | `PYPI_API_TOKEN` |
+| `docker-publish.yml` | ghcr.io (`agentexec-worker`) | `GITHUB_TOKEN` (built-in) |
+| `npm-publish.yml` | npm (`agentexec-ui`) | `NPM_TOKEN` |
+
+Docker and npm publishing can also be triggered manually via workflow dispatch.
+
+## Steps
+
+### 1. Ensure CI is green
+
+Push all changes to `main` and verify the CI workflow passes (unit tests on
+Python 3.12/3.13 and Kafka integration tests).
+
+### 2. Bump the version
+
+Update the version in `pyproject.toml`:
+
+```toml
+version = "X.Y.Z"      # stable release
+version = "X.Y.ZrcN"   # release candidate
+```
+
+For the UI package, also update `ui/package.json`.
+
+Commit and push:
+
+```bash
+git add pyproject.toml
+git commit -m "Bump version to X.Y.Z"
+git push
+```
+
+### 3. Update CHANGELOG.md
+
+Add a new section at the top of `CHANGELOG.md` with release notes covering
+breaking changes, new features, improvements, bug fixes, and testing updates.
+
+### 4. Tag the release
+
+```bash
+git tag vX.Y.Z
+git push origin vX.Y.Z
+```
+
+### 5. Create the GitHub Release
+
+This is what triggers the publish workflows.
+
+```bash
+gh release create vX.Y.Z --title "vX.Y.Z" --notes-file CHANGELOG.md
+```
+
+For release candidates, mark as a pre-release:
+
+```bash
+gh release create vX.Y.ZrcN --title "vX.Y.ZrcN" --generate-notes --prerelease
+```
+
+### 6. Verify
+
+Check that all three publish workflows succeeded:
+
+```bash
+gh run list --limit 5
+```
+
+- **PyPI**: https://pypi.org/project/agentexec/
+- **Docker**: https://ghcr.io/agent-ci/agentexec-worker
+- **npm**: https://www.npmjs.com/package/agentexec-ui
+
+## Manual Publishing
+
+Docker and npm workflows support manual dispatch for one-off builds:
+
+```bash
+# Docker with a custom tag
+gh workflow run docker-publish.yml -f tag=dev
+
+# npm with a version override
+gh workflow run npm-publish.yml -f version=0.2.0-beta.1
+```

agentexec-0.2.0rc2/examples/basic/debug_spawn.py

@@ -0,0 +1,30 @@
+"""Debug: patch Worker to print tasks dict on startup, then run via Pool.run()."""
+import sys
+import os
+import logging
+
+sys.path.insert(0, os.getcwd())
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="[%(levelname)s/%(processName)s] %(name)s: %(message)s",
+)
+
+from worker import pool
+from agentexec.worker.pool import Worker
+
+_orig_init = Worker.__init__
+
+def _debug_init(self, worker_id, context):
+    _orig_init(self, worker_id, context)
+    print(f"[DEBUG] Worker {worker_id} context.tasks = {list(context.tasks.keys())}", flush=True)
+    print(f"[DEBUG] Worker {worker_id} sys.path[:5] = {sys.path[:5]}", flush=True)
+
+Worker.__init__ = _debug_init
+
+from agentexec.config import CONF
+CONF.num_workers = 1
+
+if __name__ == "__main__":
+    print(f"[DEBUG] Parent tasks = {list(pool._context.tasks.keys())}")
+    pool.run()

agentexec-0.2.0rc2/examples/basic/enqueue.py

@@ -0,0 +1,26 @@
+"""Enqueue tasks for the worker pool.
+
+Simulates what an API server would do when a user submits work.
+
+Usage:
+    uv run python enqueue.py
+"""
+
+import asyncio
+
+import agentexec as ax
+from worker import ResearchContext, GreetContext, ErrorContext
+
+
+async def main():
+    await ax.enqueue("research", ResearchContext(company="Anthropic"))
+    await ax.enqueue("research", ResearchContext(company="OpenAI"))
+    await ax.enqueue("greet", GreetContext(name="World"))
+    await ax.enqueue("error", ErrorContext())
+
+    print("Enqueued 4 tasks")
+    return
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

agentexec-0.2.0rc2/examples/basic/entrypoint.sh

@@ -0,0 +1,2 @@
+#!/bin/sh
+agentexec run worker:pool --create-tables

agentexec-0.2.0rc2/examples/basic/worker.py

@@ -0,0 +1,50 @@
+"""Task definitions for the basic example.
+
+This module is imported by both the run script and the spawned worker
+processes. Keep it free of side effects — no asyncio.run(), no table
+creation, no enqueue calls.
+"""
+
+import asyncio
+import logging
+from uuid import UUID
+
+from pydantic import BaseModel
+from sqlalchemy.ext.asyncio import create_async_engine
+
+import agentexec as ax
+
+logger = logging.getLogger(__name__)
+
+engine = create_async_engine("sqlite+aiosqlite:///agents.db")
+pool = ax.Pool(engine=engine)
+
+
+class ResearchContext(BaseModel):
+    company: str
+
+
+class GreetContext(BaseModel):
+    name: str
+
+
+class ErrorContext(BaseModel):
+    pass
+
+
+@pool.task("research")
+async def research(agent_id: UUID, context: ResearchContext):
+    logger.info(f"Researching {context.company}...")
+    await asyncio.sleep(1)
+    logger.info(f"Done researching {context.company}")
+
+
+@pool.task("greet")
+async def greet(agent_id: UUID, context: GreetContext):
+    logger.info(f"Hello, {context.name}!")
+
+
+@pool.task("error")
+async def handle_error(agent_id: UUID, context: ErrorContext) -> None:
+    logger.info("This will throw an error")
+    raise Exception("Intentional error")

{agentexec-0.2.0rc1 → agentexec-0.2.0rc2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentexec"
-version = "0.2.0rc1"
+version = "0.2.0rc2"
 description = "Production-ready orchestration for OpenAI Agents with Redis-backed coordination, activity tracking, and workflow management"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -23,7 +23,7 @@ dependencies = [
     "redis>=7.0.1",
     "pydantic>=2.12.0",
     "pydantic-settings>=2.5.0",
-    "sqlalchemy>=2.0.44",
+    "sqlalchemy[asyncio]>=2.0.44",
     "openai-agents>=0.1.0",
     "croniter>=6.0.0",
 ]
@@ -34,6 +34,9 @@ kafka = [
 ]
 
 
+[project.scripts]
+agentexec = "agentexec.cli:main"
+
 [project.urls]
 Homepage = "https://github.com/Agent-CI/agentexec"
 Documentation = "https://github.com/Agent-CI/agentexec#readme"
@@ -47,8 +50,8 @@ build-backend = "hatchling.build"
 [tool.hatch.build.targets.wheel]
 packages = ["src/agentexec"]
 
-[tool.uv]
-dev-dependencies = [
+[dependency-groups]
+dev = [
     "pytest>=8.0.0",
     "pytest-asyncio>=0.23.0",
     "pytest-cov>=4.1.0",
@@ -56,10 +59,11 @@ dev-dependencies = [
     "ty>=0.0.1a7",
     "fakeredis>=2.32.1",
     "pytest-ty>=0.1.3",
+    "aiosqlite>=0.22.1",
 ]
 
 [tool.ruff]
-line-length = 100
+line-length = 110
 target-version = "py312"
 
 [tool.ty.environment]