agentexec 0.1.2__tar.gz → 0.1.3__tar.gz

agentexec-0.1.3/.github/workflows/docker-publish.yml

@@ -0,0 +1,65 @@
+name: Publish Docker Image
+
+on:
+  release:
+    types: [published]
+  # Allow manual trigger for testing
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Image tag (defaults to "dev")'
+        required: false
+        default: 'dev'
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: agent-ci/agentexec-worker
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            # Tag with version on release (e.g., v0.1.2 -> 0.1.2)
+            type=semver,pattern={{version}}
+            # Tag with major.minor on release (e.g., v0.1.2 -> 0.1)
+            type=semver,pattern={{major}}.{{minor}}
+            # Tag as "latest" on release
+            type=raw,value=latest,enable=${{ github.event_name == 'release' }}
+            # Tag with input value on manual dispatch
+            type=raw,value=${{ inputs.tag }},enable=${{ github.event_name == 'workflow_dispatch' }}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: ./docker
+          file: ./docker/Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          platforms: linux/amd64,linux/arm64

agentexec-0.1.3/.github/workflows/npm-publish.yml

@@ -0,0 +1,48 @@
+name: Publish agentexec-ui to npm
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to publish (leave empty to use package.json version)'
+        required: false
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    # Only run for releases tagged with ui-v* or manual triggers
+    if: github.event_name == 'workflow_dispatch' || startsWith(github.ref, 'refs/tags/ui-v')
+    runs-on: ubuntu-latest
+
+    defaults:
+      run:
+        working-directory: ui
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+        registry-url: 'https://registry.npmjs.org'
+
+    - name: Install dependencies
+      run: npm install
+
+    - name: Update version (if specified)
+      if: inputs.version != ''
+      run: npm version ${{ inputs.version }} --no-git-tag-version
+
+    - name: Build package
+      run: npm run build
+
+    - name: Publish to npm
+      run: npm publish --access public
+      env:
+        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

agentexec-0.1.3/CHANGELOG.md

@@ -0,0 +1,171 @@
+# Changelog
+
+## Unreleased
+
+### Breaking Changes
+
+**Self-describing JSON serialization replaces pickle**
+- Task results now use JSON serialization with embedded type information (similar to pickle)
+- Automatically stores fully qualified class name with data for type reconstruction
+- No longer requires `TaskDefinition` registry for result deserialization
+- `ax.gather()` now works with tasks created via `ax.enqueue()` without pool context
+- **Migration**: Clear Redis or wait for TTL expiry on old pickled results
+
+**TaskHandler Protocol enforces BaseModel returns**
+- Task handlers must return a Pydantic `BaseModel` instance (not `None` or arbitrary objects)
+- Return type is automatically inferred and validated at registration time
+- Enables type-safe result retrieval and automatic serialization
+
+### New Features
+
+**State backend abstraction**
+- Introduced `StateBackend` Protocol for pluggable state storage implementations
+- Current Redis implementation moved to `agentexec.state.redis_backend`
+- Backend modules verified against protocol at import time via `cast()`
+- Prepares foundation for alternative backends (in-memory, DynamoDB, etc.)
+
+**Improved async patterns**
+- `brpop()` is now a proper async function (was sync returning coroutine)
+- Consistent async/await usage across state operations
+- Better type hints and IDE support
+
+**Enhanced type safety**
+- `TaskHandler` Protocol with support for both sync and async handlers
+- Proper type annotations for all state backend operations
+- `serialize()` and `deserialize()` type-enforced for `BaseModel` only
+
+### Documentation
+
+**Comprehensive documentation added**
+- API reference for core modules (activity, pipeline, runner, task)
+- Conceptual guides (architecture, task lifecycle, worker pool)
+- Deployment guides (Docker, production best practices)
+- Usage guides (basic usage, pipelines, FastAPI integration, OpenAI runner)
+- Getting started (installation, quickstart, configuration)
+- Contributing guide
+
+### UI & Tooling
+
+**React frontend and component library**
+- Added `agentexec-ui` npm package with reusable React components
+- Pre-built UI for agent monitoring and activity tracking
+- TanStack Query integration for real-time updates
+- React Router for navigation between agent list and detail views
+
+**Docker deployment**
+- Docker worker image for containerized deployments
+- GitHub Actions for automated Docker image publishing to GitHub Container Registry
+- GitHub Actions for automated npm publishing of UI components
+
+### Testing
+
+**Comprehensive test coverage**
+- Achieved 89% code coverage
+- Added unit tests for all core modules:
+  - State backend and serialization (`test_state.py`, `test_state_backend.py`)
+  - Self-describing results (`test_self_describing_results.py`)
+  - Activity tracking schemas (`test_activity_schemas.py`)
+  - Pipeline orchestration (`test_pipeline.py`)
+  - Task queue operations (`test_queue.py`)
+  - Worker events and logging (`test_worker_event.py`, `test_worker_logging.py`)
+  - Database operations (`test_db.py`)
+  - Configuration (`test_config.py`)
+
+### Internal Improvements
+
+**Redis client refactoring**
+- Removed `core/redis_client.py` in favor of state backend abstraction
+- Lazy connection initialization for both async and sync Redis clients
+- Proper connection cleanup in `backend.close()`
+
+**Key formatting consistency**
+- All state keys use consistent `agentexec:` prefix via `backend.format_key()`
+- Results: `agentexec:result:{agent_id}`
+- Events: `agentexec:event:{name}:{id}`
+- Logs channel: `agentexec:logs`
+
+**Standardized function signatures**
+- `get_result()` and `gather()` return `BaseModel` directly (not JSON strings)
+- Consistent parameter ordering across state module functions
+- Better docstrings with type information
+
+## v0.1.2
+
+### New Features
+
+**Pipelines**
+- Multi-step workflow orchestration with `ax.Pipeline`
+- Define steps with `@pipeline.step(order)` decorator
+- Parallel task execution with `ax.gather()`
+- Result retrieval with `ax.get_result()`
+
+**Worker logging via Redis pubsub**
+- Workers publish logs to Redis, collected by main process
+- Use `pool.run()` to see worker logs in real-time
+
+### Internal Improvements
+
+**Reorganized worker module**
+- Worker code moved to `agentexec.worker` subpackage
+- `RedisEvent` for cross-process shutdown coordination
+- `get_worker_logger()` configures logging and returns logger in one call
+
+**Refactored Redis client usage**
+- Added `get_redis_sync()` for synchronous Redis operations
+- Sync/async Redis clients for different contexts
+
+## v0.1.1
+
+### Breaking Changes
+
+**Async `enqueue()` function**
+- `ax.enqueue()` is now async and must be awaited:
+  ```python
+  task = await ax.enqueue("task_name", MyContext(key="value"))
+  ```
+
+**Type-safe context with Pydantic BaseModel**
+- Task context must be a Pydantic `BaseModel` instead of a raw `dict`
+- Context class is automatically inferred from handler type hints:
+  ```python
+  class ResearchContext(BaseModel):
+      company: str
+
+  @pool.task("research")
+  async def research(agent_id: UUID, context: ResearchContext):
+      company = context.company  # Type-safe with IDE autocomplete
+  ```
+
+**Redis URL now required**
+- `redis_url` defaults to `None` and must be explicitly configured via `REDIS_URL`
+- Prevents accidental connections to wrong Redis instances
+
+### New Features
+
+**Configurable activity messages**
+- Activity status messages are configurable via environment variables:
+  ```bash
+  AGENTEXEC_ACTIVITY_MESSAGE_CREATE="Waiting to start."
+  AGENTEXEC_ACTIVITY_MESSAGE_STARTED="Task started."
+  AGENTEXEC_ACTIVITY_MESSAGE_COMPLETE="Task completed successfully."
+  AGENTEXEC_ACTIVITY_MESSAGE_ERROR="Task failed with error: {error}"
+  ```
+
+**Improved Task architecture**
+- `Task` is now the primary execution object with `execute()` method
+- `TaskDefinition` handles registration metadata and context class inference
+- Full lifecycle management (QUEUED → RUNNING → COMPLETE/ERROR) encapsulated in `Task.execute()`
+
+**Better SQLAlchemy session management**
+- New `scoped_session` pattern for worker processes
+- Proper session cleanup on worker shutdown
+
+### Internal Improvements
+
+- Switched to async Redis client (`redis.asyncio`)
+- Consolidated cleanup code in worker `_run()` method
+- Removed unused `debug` config option
+
+## v0.1.0
+
+Initial release.

{agentexec-0.1.2 → agentexec-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentexec
-Version: 0.1.2
+Version: 0.1.3
 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
@@ -25,6 +25,8 @@ Description-Content-Type: text/markdown
 
 # `agentexec`
 
+[![codecov](https://codecov.io/gh/Agent-CI/agentexec/branch/main/graph/badge.svg)](https://codecov.io/gh/Agent-CI/agentexec)
+
 **Production-ready orchestration for OpenAI Agents SDK** with Redis-backed task queues, SQLAlchemy activity tracking, and multiprocessing worker pools.
 
 Build reliable, scalable AI agent applications with automatic lifecycle management, progress tracking, and fault tolerance.
@@ -243,7 +245,7 @@ class MyPipeline(pipeline.Base):
     async def analyze(self, brand_result, market_result):
         """Combine results from previous step."""
         task = await ax.enqueue("analyze", AnalysisContext(...))
-        return await ax.get_result(task.agent_id)
+        return await ax.get_result(task)
 
 
 # Run the pipeline
@@ -394,6 +396,49 @@ AgentExec creates two tables (prefix configurable):
 
 ---
 
+## Docker Deployment
+
+Deploy workers using the official Docker image:
+
+### 1. Create your worker Dockerfile
+
+```dockerfile
+FROM ghcr.io/agent-ci/agentexec-worker:latest
+
+COPY ./src /app/src
+ENV AGENTEXEC_WORKER_MODULE=src.worker
+```
+
+### 2. Create your worker module
+
+```python
+# src/worker.py
+import os
+import agentexec as ax
+
+pool = ax.WorkerPool(database_url=os.environ["DATABASE_URL"])
+
+@pool.task("my_task")
+async def my_task(agent_id, context):
+    # Your task implementation
+    pass
+```
+
+### 3. Run with Docker
+
+```bash
+docker build -t my-worker .
+docker run \
+  -e DATABASE_URL=postgresql://... \
+  -e REDIS_URL=redis://... \
+  -e OPENAI_API_KEY=sk-... \
+  my-worker
+```
+
+See **[docker/README.md](docker/README.md)** for full documentation including Docker Compose examples.
+
+---
+
 ## Development
 
 ```bash

{agentexec-0.1.2 → agentexec-0.1.3}/README.md

@@ -1,5 +1,7 @@
 # `agentexec`
 
+[![codecov](https://codecov.io/gh/Agent-CI/agentexec/branch/main/graph/badge.svg)](https://codecov.io/gh/Agent-CI/agentexec)
+
 **Production-ready orchestration for OpenAI Agents SDK** with Redis-backed task queues, SQLAlchemy activity tracking, and multiprocessing worker pools.
 
 Build reliable, scalable AI agent applications with automatic lifecycle management, progress tracking, and fault tolerance.
@@ -218,7 +220,7 @@ class MyPipeline(pipeline.Base):
     async def analyze(self, brand_result, market_result):
         """Combine results from previous step."""
         task = await ax.enqueue("analyze", AnalysisContext(...))
-        return await ax.get_result(task.agent_id)
+        return await ax.get_result(task)
 
 
 # Run the pipeline
@@ -369,6 +371,49 @@ AgentExec creates two tables (prefix configurable):
 
 ---
 
+## Docker Deployment
+
+Deploy workers using the official Docker image:
+
+### 1. Create your worker Dockerfile
+
+```dockerfile
+FROM ghcr.io/agent-ci/agentexec-worker:latest
+
+COPY ./src /app/src
+ENV AGENTEXEC_WORKER_MODULE=src.worker
+```
+
+### 2. Create your worker module
+
+```python
+# src/worker.py
+import os
+import agentexec as ax
+
+pool = ax.WorkerPool(database_url=os.environ["DATABASE_URL"])
+
+@pool.task("my_task")
+async def my_task(agent_id, context):
+    # Your task implementation
+    pass
+```
+
+### 3. Run with Docker
+
+```bash
+docker build -t my-worker .
+docker run \
+  -e DATABASE_URL=postgresql://... \
+  -e REDIS_URL=redis://... \
+  -e OPENAI_API_KEY=sk-... \
+  my-worker
+```
+
+See **[docker/README.md](docker/README.md)** for full documentation including Docker Compose examples.
+
+---
+
 ## Development
 
 ```bash

agentexec-0.1.3/docker/Dockerfile

@@ -0,0 +1,77 @@
+# agentexec-worker base image
+#
+# This image provides the agentexec framework for running background workers.
+# Users extend this image with their own task definitions.
+#
+# Usage:
+#   FROM ghcr.io/agent-ci/agentexec-worker:latest
+#   COPY ./src /app/src
+#   ENV AGENTEXEC_WORKER_MODULE=src.worker
+#
+# Required environment variables at runtime:
+#   DATABASE_URL - Database connection URL (e.g., postgresql://...)
+#   REDIS_URL - Redis connection URL (e.g., redis://...)
+#   AGENTEXEC_WORKER_MODULE - Python module path with pool definition
+#
+# Optional environment variables:
+#   OPENAI_API_KEY - Required if using OpenAI agents
+#   AGENTEXEC_NUM_WORKERS - Number of worker processes (default: 4)
+#   AGENTEXEC_QUEUE_NAME - Redis queue name (default: agentexec_tasks)
+
+FROM python:3.11-slim AS base
+
+# Prevent Python from writing pyc files and buffering stdout/stderr
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    # Ensure Python can find modules in /app
+    PYTHONPATH=/app
+
+WORKDIR /app
+
+# Install system dependencies for database drivers
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    # PostgreSQL client library (for psycopg2)
+    libpq5 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Build stage for compiling dependencies
+FROM base AS builder
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    # Build tools
+    gcc \
+    # PostgreSQL dev headers (for psycopg2)
+    libpq-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install pip dependencies
+RUN pip install --no-cache-dir --upgrade pip
+
+# Install agentexec with common database drivers
+# Users can extend with additional drivers as needed
+RUN pip install --no-cache-dir \
+    agentexec \
+    psycopg2-binary \
+    # For async PostgreSQL (optional, commonly used)
+    asyncpg
+
+# Final stage
+FROM base AS runtime
+
+# Copy installed packages from builder
+COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
+COPY --from=builder /usr/local/bin /usr/local/bin
+
+# Copy entrypoint script
+COPY entrypoint.py /app/entrypoint.py
+
+# Create non-root user for security
+RUN useradd --create-home --shell /bin/bash worker
+USER worker
+
+# Health check - verify Python and agentexec are available
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD python -c "import agentexec" || exit 1
+
+# Default command runs the worker entrypoint
+ENTRYPOINT ["python", "/app/entrypoint.py"]

agentexec-0.1.3/docker/README.md

@@ -0,0 +1,149 @@
+# agentexec-worker Docker Image
+
+Base Docker image for deploying agentexec workers.
+
+## Quick Start
+
+### 1. Create your worker module
+
+```python
+# src/worker.py
+import os
+import agentexec as ax
+
+pool = ax.WorkerPool(database_url=os.environ["DATABASE_URL"])
+
+@pool.task("my_task")
+async def my_task(agent_id, context):
+    # Your task implementation
+    pass
+```
+
+### 2. Create your Dockerfile
+
+```dockerfile
+FROM ghcr.io/agent-ci/agentexec-worker:latest
+
+# Copy your application code
+COPY ./src /app/src
+
+# Point to your worker module
+ENV AGENTEXEC_WORKER_MODULE=src.worker
+```
+
+### 3. Build and run
+
+```bash
+# Build your image
+docker build -t my-worker .
+
+# Run with required environment variables
+docker run \
+  -e DATABASE_URL=postgresql://user:pass@host:5432/db \
+  -e REDIS_URL=redis://host:6379 \
+  -e OPENAI_API_KEY=sk-... \
+  my-worker
+```
+
+## Environment Variables
+
+### Required
+
+| Variable | Description |
+|----------|-------------|
+| `DATABASE_URL` | Database connection URL |
+| `REDIS_URL` | Redis connection URL |
+| `AGENTEXEC_WORKER_MODULE` | Python module path containing `pool` |
+
+### Optional
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OPENAI_API_KEY` | - | Required if using OpenAI agents |
+| `AGENTEXEC_NUM_WORKERS` | 4 | Number of worker processes |
+| `AGENTEXEC_QUEUE_NAME` | agentexec_tasks | Redis queue name |
+| `AGENTEXEC_GRACEFUL_SHUTDOWN_TIMEOUT` | 300 | Shutdown timeout (seconds) |
+| `AGENTEXEC_RESULT_TTL` | 3600 | Task result TTL (seconds) |
+
+## Worker Module Requirements
+
+Your worker module must expose either:
+
+1. A `pool` variable (recommended):
+   ```python
+   pool = ax.WorkerPool(database_url=os.environ["DATABASE_URL"])
+   ```
+
+2. Or a `create_pool()` function:
+   ```python
+   def create_pool():
+       return ax.WorkerPool(database_url=os.environ["DATABASE_URL"])
+   ```
+
+## Docker Compose Example
+
+```yaml
+version: '3.8'
+
+services:
+  worker:
+    build: .
+    environment:
+      - DATABASE_URL=postgresql://postgres:postgres@db:5432/app
+      - REDIS_URL=redis://redis:6379
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - AGENTEXEC_NUM_WORKERS=2
+    depends_on:
+      - db
+      - redis
+
+  db:
+    image: postgres:15
+    environment:
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: app
+
+  redis:
+    image: redis:7-alpine
+```
+
+## Extending the Image
+
+### Adding Python dependencies
+
+```dockerfile
+FROM ghcr.io/agent-ci/agentexec-worker:latest
+
+# Install additional packages
+RUN pip install --no-cache-dir \
+    httpx \
+    beautifulsoup4
+
+COPY ./src /app/src
+ENV AGENTEXEC_WORKER_MODULE=src.worker
+```
+
+### Using a different database
+
+The base image includes `psycopg2-binary` for PostgreSQL. For other databases:
+
+```dockerfile
+FROM ghcr.io/agent-ci/agentexec-worker:latest
+
+# For MySQL
+RUN pip install --no-cache-dir mysqlclient
+
+# For SQLite (included in Python stdlib, but you may want async driver)
+RUN pip install --no-cache-dir aiosqlite
+```
+
+## Building Locally
+
+```bash
+cd docker
+docker build -t agentexec-worker .
+```
+
+## Multi-Architecture Support
+
+The published image supports both `linux/amd64` and `linux/arm64` architectures.