fableforge-agent-runtime 0.1.0__tar.gz

fableforge_agent_runtime-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,38 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  id-token: write
+  packages: write
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/fableforge-agent-runtime
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build dependencies
+        run: python -m pip install --upgrade build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

fableforge_agent_runtime-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+*.so
+.env

fableforge_agent_runtime-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 FableForge Contributors
+
+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.

fableforge_agent_runtime-0.1.0/PKG-INFO

@@ -0,0 +1,274 @@
+Metadata-Version: 2.4
+Name: fableforge-agent-runtime
+Version: 0.1.0
+Summary: Persistent agent daemon — systemd for AI agents
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.111.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: redis>=5.0.0
+Requires-Dist: sqlalchemy>=2.0.30
+Requires-Dist: uvicorn[standard]>=0.30.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AgentRuntime — systemd for AI Agents
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/) [![Tests](https://img.shields.io/badge/tests-0-yellow.svg)](tests/)
+
+
+A persistent agent daemon that manages AI agent processes, serializes state, and resumes sessions. Think of it as **systemd for AI agents** — start, pause, resume, and checkpoint agent sessions with full state persistence.
+
+## Architecture
+
+```
+┌─────────────┐     ┌──────────────────┐     ┌────────────────┐
+│   CLI       │────▶│   FastAPI Server │────▶│  SessionManager│
+│  (agentd)   │     │   (port 8721)    │     │                │
+└─────────────┘     └──────────────────┘     └───────┬────────┘
+                                                      │
+                              ┌─────────────────────────┼─────────────────────┐
+                              │                         │                     │
+                     ┌────────▼────────┐      ┌────────▼────────┐   ┌───────▼──────┐
+                     │ StateSerializer │      │   MemoryStore   │   │    Daemon     │
+                     │   (SQLite)      │      │  (Short+Long)   │   │  (Heartbeat)  │
+                     └─────────────────┘      └─────────────────┘   └──────────────┘
+```
+
+## Features
+
+- **Session Lifecycle**: Create, start, pause, resume, stop agent sessions
+- **State Persistence**: Full session state serialized to SQLite
+- **Checkpoints**: Save and restore complete state at any point
+- **Memory Management**: Short-term (conversation context) and long-term (key-value with semantic search)
+- **Memory Consolidation**: Auto-summarize old short-term memories
+- **Auto-Checkpoint**: Configurable interval for automatic state snapshots
+- **Graceful Shutdown**: State preservation on daemon stop
+- **Session Timeout**: Automatic cleanup of stopped sessions
+- **REST API**: Full HTTP API via FastAPI
+- **CLI**: Command-line interface for all operations
+- **Docker**: Production-ready container image
+
+## Quick Start
+
+### Install
+
+```bash
+pip install -e .
+```
+
+### Start the Daemon
+
+```bash
+agentd start --port 8721
+```
+
+### Create a Session
+
+```bash
+agentd create --name "my-agent" --model fableforge-14b --system-prompt "You are a helpful assistant"
+```
+
+### List Sessions
+
+```bash
+agentd list
+```
+
+### Resume a Session
+
+```bash
+agentd resume <session-id> --checkpoint-id <checkpoint-id>
+```
+
+### Stop the Daemon
+
+```bash
+agentd stop
+```
+
+## API Reference
+
+### POST /sessions
+
+Create a new session.
+
+```json
+{
+  "name": "my-agent",
+  "model": "fableforge-14b",
+  "system_prompt": "You are a helpful assistant.",
+  "tools": ["search", "calculator"]
+}
+```
+
+### GET /sessions
+
+List all sessions.
+
+### GET /sessions/{id}
+
+Get session state.
+
+### POST /sessions/{id}/start
+
+Start a session (begins heartbeat and auto-checkpoint).
+
+### POST /sessions/{id}/pause
+
+Pause a running session (creates checkpoint, cancels heartbeat).
+
+### POST /sessions/{id}/resume
+
+Resume a paused or stopped session.
+
+```json
+{
+  "session_id": "abc123",
+  "checkpoint_id": "cp_456"
+}
+```
+
+### POST /sessions/{id}/stop
+
+Stop a session (creates final checkpoint).
+
+### GET /sessions/{id}/memory
+
+List memory keys or retrieve specific key: `?key=my_key`
+
+### POST /sessions/{id}/memory
+
+Store a memory entry.
+
+```json
+{
+  "key": "user_preference",
+  "value": {"theme": "dark", "language": "en"}
+}
+```
+
+### GET /sessions/{id}/checkpoints
+
+List all checkpoints for a session.
+
+### POST /sessions/{id}/checkpoints
+
+Create a checkpoint. Query param: `?label=my-checkpoint`
+
+### GET /health
+
+Daemon health status.
+
+## Session States
+
+```
+CREATED ──▶ RUNNING ──◆──▶ PAUSED ──▶ RUNNING
+              │    │         │
+              │    └──▶ STOPPED
+              └──▶ ERROR
+```
+
+## Memory Architecture
+
+### Short-Term Memory
+
+- Last N messages per session (default 50)
+- Automatic pruning when window exceeded
+- Used for conversation context
+
+### Long-Term Memory
+
+- Key-value store with optional embeddings
+- Cosine similarity semantic search
+- Persistent across sessions
+- Consolidation: summarizes old short-term into long-term
+
+### Consolidation
+
+When short-term memory exceeds a threshold, the daemon:
+1. Summarizes the recent conversation
+2. Stores the summary in long-term memory
+3. Prunes old short-term entries
+
+## Configuration
+
+| Env Variable | Default | Description |
+|---|---|---|
+| `AGENT_RUNTIME_DB` | `~/.agent_runtime/state.db` | SQLite database path |
+| `AGENT_RUNTIME_MEMORY_DB` | `~/.agent_runtime/memory.db` | Memory database path |
+| `AGENT_RUNTIME_PORT` | `8721` | HTTP server port |
+| `AGENT_RUNTIME_HOST` | `0.0.0.0` | HTTP server bind address |
+| `AGENT_RUNTIME_CHECKPOINT_INTERVAL` | `60` | Auto-checkpoint interval (seconds) |
+| `AGENT_RUNTIME_SESSION_TIMEOUT` | `3600` | Session timeout (seconds) |
+
+## Docker
+
+```bash
+docker build -f docker/Dockerfile -t agent-runtime .
+docker run -p 8721:8721 -v agent_data:/root/.agent_runtime agent-runtime
+```
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+## Project Structure
+
+```
+agent-runtime/
+├── pyproject.toml
+├── docker/
+│   └── Dockerfile
+├── src/
+│   └── agent_runtime/
+│       ├── __init__.py
+│       ├── models.py              # Pydantic models
+│       ├── state_serializer.py    # SQLite state persistence
+│       ├── memory_store.py        # Short/long-term memory
+│       ├── session_manager.py     # Session lifecycle
+│       ├── daemon.py              # Background daemon process
+│       ├── server.py              # FastAPI HTTP server
+│       └── cli.py                 # CLI interface
+├── tests/
+│   └── test_state_serializer.py
+└── README.md
+```
+
+## License
+
+MIT
+
+## Ecosystem
+
+Part of the [FableForge](../) ecosystem — 21 open-source projects built from 210K real agent traces:
+
+| Project | Description |
+| --- | --- |
+| **[Anvil](../anvil)** | Self-verified coding agent |
+| **[VerifyLoop](../verifyloop)** | Plan→Execute→Verify→Recover framework |
+| **[ErrorRecovery](../error-recovery)** | Self-healing middleware (3,725 error patterns) |
+| **[FableForge-14B](../fableforge-14b)** | The fine-tuned 14B model (4-stage training) |
+| **[ShellWhisperer](../shell-whisperer)** | 1.5B edge agent (phone/RPi, 50ms) |
+| **[ReasonCritic](../reason-critic)** | Verification model (130 benchmark tasks) |
+| **[TraceCompiler](../trace-compiler)** | Compile traces → LoRA skills |
+| **[AgentRuntime](../agent-runtime)** | Persistent agent daemon (systemd for AI) |
+| **[AgentSwarm](../agent-swarm)** | Multi-agent from real trace transitions |
+| **[AgentTelemetry](../agent-telemetry)** | Datadog for agents (token tracking, costs) |
+| **[BenchAgent](../bench-agent)** | HumanEval for tool-use (107 tasks) |
+| **[AgentDev](../agent-dev)** | VSCode extension with verification |
+| **[TraceViz](../trace-viz)** | Trace replay visualizer (Next.js) |
+| **[AgentSkills](../agent-skills)** | npm for agent behaviors |
+| **[AgentCurriculum](../agent-curriculum)** | 5-stage progressive training |
+| **[AgentFuzzer](../agent-fuzzer)** | Adversarial testing for agents |
+| **[AgentConstitution](../agent-constitution)** | Safety guardrails from traces |
+| **[CostOptimizer](../cost-optimizer)** | Token cost reduction (50-80%) |
+| **[AgentProfiler](../agent-profiler)** | Behavioral fingerprinting |
+| **[TrajectoryDistiller](../trajectory-distiller)** | Trace→training data pipeline |
+| **[Fable5-Dataset](../fable5-dataset)** | HuggingFace dataset release |

fableforge_agent_runtime-0.1.0/README.md

@@ -0,0 +1,257 @@
+# AgentRuntime — systemd for AI Agents
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/) [![Tests](https://img.shields.io/badge/tests-0-yellow.svg)](tests/)
+
+
+A persistent agent daemon that manages AI agent processes, serializes state, and resumes sessions. Think of it as **systemd for AI agents** — start, pause, resume, and checkpoint agent sessions with full state persistence.
+
+## Architecture
+
+```
+┌─────────────┐     ┌──────────────────┐     ┌────────────────┐
+│   CLI       │────▶│   FastAPI Server │────▶│  SessionManager│
+│  (agentd)   │     │   (port 8721)    │     │                │
+└─────────────┘     └──────────────────┘     └───────┬────────┘
+                                                      │
+                              ┌─────────────────────────┼─────────────────────┐
+                              │                         │                     │
+                     ┌────────▼────────┐      ┌────────▼────────┐   ┌───────▼──────┐
+                     │ StateSerializer │      │   MemoryStore   │   │    Daemon     │
+                     │   (SQLite)      │      │  (Short+Long)   │   │  (Heartbeat)  │
+                     └─────────────────┘      └─────────────────┘   └──────────────┘
+```
+
+## Features
+
+- **Session Lifecycle**: Create, start, pause, resume, stop agent sessions
+- **State Persistence**: Full session state serialized to SQLite
+- **Checkpoints**: Save and restore complete state at any point
+- **Memory Management**: Short-term (conversation context) and long-term (key-value with semantic search)
+- **Memory Consolidation**: Auto-summarize old short-term memories
+- **Auto-Checkpoint**: Configurable interval for automatic state snapshots
+- **Graceful Shutdown**: State preservation on daemon stop
+- **Session Timeout**: Automatic cleanup of stopped sessions
+- **REST API**: Full HTTP API via FastAPI
+- **CLI**: Command-line interface for all operations
+- **Docker**: Production-ready container image
+
+## Quick Start
+
+### Install
+
+```bash
+pip install -e .
+```
+
+### Start the Daemon
+
+```bash
+agentd start --port 8721
+```
+
+### Create a Session
+
+```bash
+agentd create --name "my-agent" --model fableforge-14b --system-prompt "You are a helpful assistant"
+```
+
+### List Sessions
+
+```bash
+agentd list
+```
+
+### Resume a Session
+
+```bash
+agentd resume <session-id> --checkpoint-id <checkpoint-id>
+```
+
+### Stop the Daemon
+
+```bash
+agentd stop
+```
+
+## API Reference
+
+### POST /sessions
+
+Create a new session.
+
+```json
+{
+  "name": "my-agent",
+  "model": "fableforge-14b",
+  "system_prompt": "You are a helpful assistant.",
+  "tools": ["search", "calculator"]
+}
+```
+
+### GET /sessions
+
+List all sessions.
+
+### GET /sessions/{id}
+
+Get session state.
+
+### POST /sessions/{id}/start
+
+Start a session (begins heartbeat and auto-checkpoint).
+
+### POST /sessions/{id}/pause
+
+Pause a running session (creates checkpoint, cancels heartbeat).
+
+### POST /sessions/{id}/resume
+
+Resume a paused or stopped session.
+
+```json
+{
+  "session_id": "abc123",
+  "checkpoint_id": "cp_456"
+}
+```
+
+### POST /sessions/{id}/stop
+
+Stop a session (creates final checkpoint).
+
+### GET /sessions/{id}/memory
+
+List memory keys or retrieve specific key: `?key=my_key`
+
+### POST /sessions/{id}/memory
+
+Store a memory entry.
+
+```json
+{
+  "key": "user_preference",
+  "value": {"theme": "dark", "language": "en"}
+}
+```
+
+### GET /sessions/{id}/checkpoints
+
+List all checkpoints for a session.
+
+### POST /sessions/{id}/checkpoints
+
+Create a checkpoint. Query param: `?label=my-checkpoint`
+
+### GET /health
+
+Daemon health status.
+
+## Session States
+
+```
+CREATED ──▶ RUNNING ──◆──▶ PAUSED ──▶ RUNNING
+              │    │         │
+              │    └──▶ STOPPED
+              └──▶ ERROR
+```
+
+## Memory Architecture
+
+### Short-Term Memory
+
+- Last N messages per session (default 50)
+- Automatic pruning when window exceeded
+- Used for conversation context
+
+### Long-Term Memory
+
+- Key-value store with optional embeddings
+- Cosine similarity semantic search
+- Persistent across sessions
+- Consolidation: summarizes old short-term into long-term
+
+### Consolidation
+
+When short-term memory exceeds a threshold, the daemon:
+1. Summarizes the recent conversation
+2. Stores the summary in long-term memory
+3. Prunes old short-term entries
+
+## Configuration
+
+| Env Variable | Default | Description |
+|---|---|---|
+| `AGENT_RUNTIME_DB` | `~/.agent_runtime/state.db` | SQLite database path |
+| `AGENT_RUNTIME_MEMORY_DB` | `~/.agent_runtime/memory.db` | Memory database path |
+| `AGENT_RUNTIME_PORT` | `8721` | HTTP server port |
+| `AGENT_RUNTIME_HOST` | `0.0.0.0` | HTTP server bind address |
+| `AGENT_RUNTIME_CHECKPOINT_INTERVAL` | `60` | Auto-checkpoint interval (seconds) |
+| `AGENT_RUNTIME_SESSION_TIMEOUT` | `3600` | Session timeout (seconds) |
+
+## Docker
+
+```bash
+docker build -f docker/Dockerfile -t agent-runtime .
+docker run -p 8721:8721 -v agent_data:/root/.agent_runtime agent-runtime
+```
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+## Project Structure
+
+```
+agent-runtime/
+├── pyproject.toml
+├── docker/
+│   └── Dockerfile
+├── src/
+│   └── agent_runtime/
+│       ├── __init__.py
+│       ├── models.py              # Pydantic models
+│       ├── state_serializer.py    # SQLite state persistence
+│       ├── memory_store.py        # Short/long-term memory
+│       ├── session_manager.py     # Session lifecycle
+│       ├── daemon.py              # Background daemon process
+│       ├── server.py              # FastAPI HTTP server
+│       └── cli.py                 # CLI interface
+├── tests/
+│   └── test_state_serializer.py
+└── README.md
+```
+
+## License
+
+MIT
+
+## Ecosystem
+
+Part of the [FableForge](../) ecosystem — 21 open-source projects built from 210K real agent traces:
+
+| Project | Description |
+| --- | --- |
+| **[Anvil](../anvil)** | Self-verified coding agent |
+| **[VerifyLoop](../verifyloop)** | Plan→Execute→Verify→Recover framework |
+| **[ErrorRecovery](../error-recovery)** | Self-healing middleware (3,725 error patterns) |
+| **[FableForge-14B](../fableforge-14b)** | The fine-tuned 14B model (4-stage training) |
+| **[ShellWhisperer](../shell-whisperer)** | 1.5B edge agent (phone/RPi, 50ms) |
+| **[ReasonCritic](../reason-critic)** | Verification model (130 benchmark tasks) |
+| **[TraceCompiler](../trace-compiler)** | Compile traces → LoRA skills |
+| **[AgentRuntime](../agent-runtime)** | Persistent agent daemon (systemd for AI) |
+| **[AgentSwarm](../agent-swarm)** | Multi-agent from real trace transitions |
+| **[AgentTelemetry](../agent-telemetry)** | Datadog for agents (token tracking, costs) |
+| **[BenchAgent](../bench-agent)** | HumanEval for tool-use (107 tasks) |
+| **[AgentDev](../agent-dev)** | VSCode extension with verification |
+| **[TraceViz](../trace-viz)** | Trace replay visualizer (Next.js) |
+| **[AgentSkills](../agent-skills)** | npm for agent behaviors |
+| **[AgentCurriculum](../agent-curriculum)** | 5-stage progressive training |
+| **[AgentFuzzer](../agent-fuzzer)** | Adversarial testing for agents |
+| **[AgentConstitution](../agent-constitution)** | Safety guardrails from traces |
+| **[CostOptimizer](../cost-optimizer)** | Token cost reduction (50-80%) |
+| **[AgentProfiler](../agent-profiler)** | Behavioral fingerprinting |
+| **[TrajectoryDistiller](../trajectory-distiller)** | Trace→training data pipeline |
+| **[Fable5-Dataset](../fable5-dataset)** | HuggingFace dataset release |

fableforge_agent_runtime-0.1.0/docker/Dockerfile

@@ -0,0 +1,24 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY pyproject.toml .
+RUN pip install --no-cache-dir .
+
+COPY src/ src/
+
+RUN pip install --no-cache-dir -e .
+
+RUN mkdir -p /root/.agent_runtime
+
+EXPOSE 8721
+
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8721/health')" || exit 1
+
+ENTRYPOINT ["agentd"]
+CMD ["start"]

fableforge_agent_runtime-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fableforge-agent-runtime"
+version = "0.1.0"
+description = "Persistent agent daemon — systemd for AI agents"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.111.0",
+    "uvicorn[standard]>=0.30.0",
+    "sqlalchemy>=2.0.30",
+    "redis>=5.0.0",
+    "pydantic>=2.7.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "httpx>=0.27",
+]
+
+[project.scripts]
+agentd = "agent_runtime.cli:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent_runtime"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

fableforge_agent_runtime-0.1.0/src/agent_runtime/__init__.py

@@ -0,0 +1,3 @@
+"""AgentRuntime — persistent agent daemon for managing AI agent processes."""
+
+__version__ = "0.1.0"