agentomatic 0.1.1__tar.gz → 0.2.0__tar.gz

{agentomatic-0.1.1 → agentomatic-0.2.0}/CHANGELOG.md

@@ -1,6 +1,28 @@
 # CHANGELOG
 
 
+## v0.2.0 (2026-06-14)
+
+### Documentation
+
+- Add telemetry and feedback correlation notes for A/B testing
+  ([`2c27a86`](https://github.com/UnicoLab/agentomatic/commit/2c27a86ac83b44a022e5d002d88316953f01ab35))
+
+### Features
+
+- Implement advanced platform features (HITL, checkpointer, structured output, fork, A/B routing,
+  fallbacks, hooks) and update documentation
+  ([`c1a55c3`](https://github.com/UnicoLab/agentomatic/commit/c1a55c39b1efd24084f1453946df27a830d3d7ec))
+
+- Increase core test coverage over 85% and enhance homepage aesthetics
+  ([`98f28f5`](https://github.com/UnicoLab/agentomatic/commit/98f28f56308b7540d642149aa2a7edc20b2eeafb))
+
+### Testing
+
+- Enhance unit test coverage for sqlalchemy store, sync checkpointers, and structured fallbacks
+  ([`91ab042`](https://github.com/UnicoLab/agentomatic/commit/91ab04254a623fb4fbd108303265ad8d4b3aeba5))
+
+
 ## v0.1.1 (2026-06-13)
 
 ### Bug Fixes

{agentomatic-0.1.1 → agentomatic-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentomatic
-Version: 0.1.1
+Version: 0.2.0
 Summary: Drop agents, not code — zero-code multi-agent API platform framework
 Project-URL: Homepage, https://github.com/UnicoLab/agentomatic
 Project-URL: Documentation, https://unicolab.github.io/agentomatic

agentomatic-0.2.0/docs/guide/platform-features.md

@@ -0,0 +1,339 @@
+# Advanced Platform Features
+
+<div align="center">
+  <img src="../assets/logo.png" width="200" alt="agentomatic logo">
+  <h3>Enterprise-Grade Orchestration & Core Capabilities</h3>
+</div>
+
+---
+
+Agentomatic provides a suite of advanced platform capabilities designed to make multi-agent systems production-ready. These features solve common real-world challenges around human-in-the-loop validation, schema enforcement, prompt routing, checkpointer persistence, and service resilience.
+
+---
+
+## 🚦 1. Human-in-the-Loop (HITL) Protocol
+
+In complex multi-agent architectures, agents often require human validation before executing sensitive actions (e.g., executing a transaction, sending an email, or performing a destructive write).
+
+Agentomatic provides a built-in suspension/resume mechanism that allows nodes or graphs to halt execution, serialize their state snapshots to the storage backend, and resume or abort dynamically when approved/rejected via HTTP.
+
+```
+                  ┌──────────────────────┐
+                  │  Agent Execution     │
+                  └──────────┬───────────┘
+                             │
+                  Node raises AgentSuspendedException
+                             │
+                             ▼
+                  ┌──────────────────────┐
+                  │ Serializes state snapshot     │
+                  │ Saves to database    │
+                  │ Returns HTTP 202     │
+                  └──────────────────────┘
+                             │
+                 ┌───────────┴───────────┐
+                 ▼                       ▼
+       POST /approve           POST /reject
+                 │                       │
+      Merges human context       Deletes snapshot
+      Resumes execution          Aborts execution
+                 │                       │
+                 ▼                       ▼
+       ┌──────────────────┐    ┌──────────────────┐
+       │   Completes graph│    │  Returns 200 OK  │
+       └──────────────────┘    └──────────────────┘
+```
+
+### Suspending Execution
+
+To suspend execution, raise `AgentSuspendedException` from anywhere inside your node function or LangGraph node:
+
+```python
+from agentomatic.core.router_factory import AgentSuspendedException
+
+async def financial_transfer_node(state: dict):
+    metadata = state.get("metadata") or {}
+    
+    # Check if we already have approval
+    if metadata.get("hitl_approved"):
+        return {
+            "response": f"Successfully transferred ${state['amount']}",
+            "metadata": metadata
+        }
+    
+    # Otherwise, suspend and wait for human confirmation
+    raise AgentSuspendedException(
+        approval_id=f"tx_{state['transaction_id']}",
+        node_name="financial_transfer_node",
+        state_snapshot=state,
+        message="Transaction requires human approval."
+    )
+```
+
+When this exception is thrown:
+1. Agentomatic intercepts the execution.
+2. The current `state_snapshot` is stored in the persistent database under `SuspendedStateModel`.
+3. The API immediately returns a `202 Accepted` status code with the approval details.
+
+**Response payload:**
+```json
+{
+  "detail": {
+    "status": "suspended",
+    "approval_id": "tx_984712",
+    "node_name": "financial_transfer_node",
+    "message": "Transaction requires human approval."
+  }
+}
+```
+
+### REST Endpoints for Approvals
+
+Each registered agent automatically exposes three endpoints to manage suspended states:
+
+#### A. List Pending Approvals
+Retrieve all currently suspended states for a specific thread.
+
+* **Method:** `GET`
+* **Path:** `/api/v1/{agent_slug}/threads/{thread_id}/pending`
+* **Response:**
+  ```json
+  {
+    "thread_id": "thread_abc123",
+    "count": 1,
+    "pending": [
+      {
+        "id": "tx_984712",
+        "node_name": "financial_transfer_node",
+        "state_snapshot": { ... },
+        "created_at": "2026-06-13T22:50:34"
+      }
+    ]
+  }
+  ```
+
+#### B. Approve and Resume Execution
+Approve the suspension, optionally merge new parameters (e.g., corrections or decisions), and resume the agent's execution from that exact step.
+
+* **Method:** `POST`
+* **Path:** `/api/v1/{agent_slug}/threads/{thread_id}/approve`
+* **Payload:**
+  ```json
+  {
+    "approval_id": "tx_984712",
+    "context": {
+      "approved_limit": 500
+    }
+  }
+  ```
+* **Behavior:** Deletes the pending suspended snapshot, merges the request's `context` into the state, marks `state.metadata.hitl_approved = True`, and resumes the graph execution synchronously. It returns the final agent execution output.
+
+#### C. Reject and Abort Execution
+Reject the transaction and discard the execution context.
+
+* **Method:** `POST`
+* **Path:** `/api/v1/{agent_slug}/threads/{thread_id}/reject`
+* **Payload:**
+  ```json
+  {
+    "approval_id": "tx_984712",
+    "reason": "Risk score too high"
+  }
+  ```
+* **Response:**
+  ```json
+  {
+    "status": "rejected",
+    "approval_id": "tx_984712",
+    "reason": "Risk score too high"
+  }
+  ```
+
+---
+
+## 💾 2. LangGraph Checkpointer (`AgentomaticCheckpointer`)
+
+If you are building your agents using **LangGraph**, you need a checkpoint saver to persist the graph's memory across invocations. Agentomatic provides a native adapter: `AgentomaticCheckpointer`.
+
+This checkpointer implements LangGraph's `BaseCheckpointSaver` and delegates storage operations directly to your configured Agentomatic `BaseStore` (e.g., `SQLAlchemyStore` or `MemoryStore`). This ensures that thread states, checkpoint namespaces, and historical tuples are stored consistently without needing a separate database.
+
+### Usage Example
+
+```python
+from langgraph.graph import StateGraph
+from agentomatic.storage import SQLAlchemyStore
+from agentomatic.storage.checkpointer import AgentomaticCheckpointer
+
+# 1. Setup your database store
+store = SQLAlchemyStore("postgresql+asyncpg://postgres:secret@localhost:5432/agent_db")
+
+# 2. Wrap it with the LangGraph checkpointer adapter
+checkpointer = AgentomaticCheckpointer(store)
+
+# 3. Create and compile your LangGraph with the checkpointer
+builder = StateGraph(MyStateClass)
+# ... build graph nodes ...
+
+graph = builder.compile(checkpointer=checkpointer)
+```
+
+All LangGraph checkpoints are automatically persisted in your database and can be fetched or updated using the standard LangGraph runtime config.
+
+---
+
+## 🎯 3. Structured Output Enforcer
+
+Ensuring that LLM outputs strictly match validation schemas is critical for reliable API integration. Agentomatic makes structured output enforcement seamless:
+
+1. **Auto-bind Schemas**: Under the hood, Agentomatic leverages LangChain's `.with_structured_output()` to bind Pydantic schemas directly to the LLM runtime.
+2. **Fallback Parser**: If the provider or mock model does not support native schema enforcement (e.g., mock/fake models in test environments), Agentomatic automatically intercepts the output and applies a robust parsing and default-fallback generator wrapper.
+
+### Factory Method
+
+Use `get_structured_llm` to create a model bound to a Pydantic schema:
+
+```python
+from pydantic import BaseModel, Field
+from agentomatic.providers.llm import get_structured_llm
+
+class TranslationOutput(BaseModel):
+    detected_language: str
+    translated_text: str
+    confidence: float = Field(default=0.0)
+
+# Build an LLM instance that returns parsed instances of TranslationOutput
+structured_model = get_structured_llm(
+    response_model=TranslationOutput,
+    provider="openai",
+    model="gpt-4o",
+    temperature=0.0
+)
+
+result = structured_model.invoke("Translate 'Bonjour tout le monde' to English")
+# 'result' is guaranteed to be a TranslationOutput object
+print(result.translated_text)  # "Hello everyone"
+```
+
+---
+
+## 🗃️ 4. Thread Forking & Cloning
+
+Debugging agent failures or performing A/B evaluation of system prompt prompts requires the ability to fork history. Agentomatic supports **Thread Forking** at the API and database levels.
+
+You can clone a parent thread starting at a specific message index. This creates a brand new thread containing a copy of all messages up to and including that index, allowing subsequent interactions to diverge without altering the parent thread's history.
+
+* **Method:** `POST`
+* **Path:** `/api/v1/{agent_slug}/threads/{thread_id}/fork`
+* **Payload:**
+  ```json
+  {
+    "message_index": 2,
+    "new_thread_id": "fork_thread_99",
+    "title": "A/B Test Variant B"
+  }
+  ```
+* **Response:** Returns the new thread dictionary:
+  ```json
+  {
+    "id": "fork_thread_99",
+    "user_id": "user_id_12",
+    "agent_name": "support_agent",
+    "title": "A/B Test Variant B",
+    "message_count": 3,
+    "metadata": {}
+  }
+  ```
+
+---
+
+## 📊 5. A/B Test Prompt Router
+
+Agentomatic enables you to easily conduct prompt version testing in production. You can configure routing splits between different system prompts directly inside your agent configuration.
+
+### Configuration
+
+Add `prompt_ab_tests` with fractional weights inside your agent's config settings:
+
+```json
+{
+  "prompt_ab_tests": {
+    "v1": 0.7,
+    "v2": 0.3
+  }
+}
+```
+
+### Execution Flow
+
+1. When a client invokes the agent without specifying a `prompt_version` (or when set to `"v1"`), Agentomatic performs a **weighted random choice** based on the configured split (in the example above: 70% traffic to `v1`, 30% traffic to `v2`).
+2. The chosen version is automatically stored in the invocation state under `state["prompt_version"]`.
+3. Your agent nodes can read `prompt_version` from the state to load the correct prompt template.
+4. The chosen version is returned in the response metadata (`metadata.prompt_version`) so that you can trace and analyze performance.
+
+### Telemetry & Feedback Correlation
+
+To measure the performance and quality of different prompt variants:
+1. **Response Tracking**: Read `metadata.prompt_version` from the `/invoke` or `/chat` JSON response payload.
+2. **Feedback Logging**: When calling the `POST /api/v1/{agent}/feedback` endpoint, pass the active prompt version in the request metadata payload:
+   ```json
+   {
+     "thread_id": "thread_123",
+     "rating": 5,
+     "comment": "Highly accurate answer!",
+     "metadata": {
+       "prompt_version": "v2"
+     }
+   }
+   ```
+   This associates ratings and comments directly with each version, allowing you to run analytical breakdowns of user satisfaction metrics per prompt variant.
+
+> [!NOTE]
+> Clients can explicitly override the A/B router by passing a specific `prompt_version` parameter in the invoke request (e.g. `{"prompt_version": "v2"}`).
+
+---
+
+## 🛡️ 6. LLM Failover & Fallbacks
+
+LLM APIs can suffer from outages, rate limiting (HTTP 429), or transient network errors. To ensure high availability, Agentomatic lets you define chainable fallback providers.
+
+### Configuration
+
+Pass a list of provider slugs in the `fallbacks` parameter of `get_llm()`:
+
+```python
+from agentomatic.providers.llm import get_llm
+
+llm = get_llm(
+    provider="openai",
+    model="gpt-4",
+    fallbacks=["azure", "ollama"]
+)
+```
+
+If the primary provider (`openai`) raises an exception during execution, LangChain's fallback mechanism automatically routes the request to the next available backup in the list (`azure`, then `ollama`), shielding clients from upstream downtime.
+
+---
+
+## 🔌 7. State-Level Hook Middleware (Interceptors)
+
+For custom telemetry, audit logging, or real-time security scanning, you can register **state-level node hooks**. These are run instantly before and after every agent node invocation.
+
+```python
+from agentomatic import AgentPlatform
+
+platform = AgentPlatform.from_folder("agents/")
+
+# 1. Register a before-node interceptor
+def audit_input_hook(agent_name: str, state: dict):
+    print(f"[Hook] Agent '{agent_name}' is about to run. Query: {state.get('current_query')}")
+    # You can inspect or modify the state inline before execution starts
+    state["metadata"]["audit_logged"] = True
+
+platform.register_before_node_hook(audit_input_hook)
+
+# 2. Register an after-node interceptor
+def audit_output_hook(agent_name: str, result: dict):
+    print(f"[Hook] Agent '{agent_name}' completed. Response snippet: {result.get('response')[:30]}")
+
+platform.register_after_node_hook(audit_output_hook)
+```

{agentomatic-0.1.1 → agentomatic-0.2.0}/docs/guide/prompts.md

@@ -99,8 +99,7 @@ If you write a custom router using `api.py` and want to load prompt templates dy
 
 ```python
 from fastapi import APIRouter
-from agentomatic import APIResponse, handle_api_errors
-from rac.agents._registry import get_registry
+from agentomatic import APIResponse, handle_api_errors, AgentRegistry
 
 router = APIRouter()
 
@@ -108,8 +107,10 @@ router = APIRouter()
 @handle_api_errors
 async def custom_chat(query: str) -> APIResponse:
     # Retrieve the agent instance from the registry
-    agent = get_registry().get_agent("my_agent")
-    
+    agent = AgentRegistry().get("my_agent")
+    if not agent:
+        return APIResponse(success=False, message="Agent not found")
+        
     # Format user prompt
     user_prompt = agent.prompt_manager.format_prompt(
         version=agent.config.prompt_version,

{agentomatic-0.1.1 → agentomatic-0.2.0}/docs/guide/storage.md

@@ -192,3 +192,13 @@ Every storage adapter implements the following async interface methods:
 | `async def get_messages(id) -> list[dict]` | **Required** | Fetch chronological chat histories |
 | `async def add_feedback(...) -> dict` | Optional | Save user scores and comment metrics |
 | `async def list_feedback(...) -> list[dict]` | Optional | Search feedback records |
+| `async def save_suspended_state(...) -> dict` | Optional | Save execution state for human approval |
+| `async def get_suspended_state(id) -> dict \| None` | Optional | Retrieve a suspended state |
+| `async def list_suspended_states(...) -> list[dict]` | Optional | List all pending suspended states |
+| `async def delete_suspended_state(id) -> bool` | Optional | Delete suspended state on completion |
+| `async def fork_thread(...) -> dict \| None` | Optional | Fork a conversation history up to index |
+| `async def save_checkpoint(...) -> None` | Optional | Save a LangGraph checkpoint state |
+| `async def get_checkpoint(...) -> dict \| None` | Optional | Retrieve a LangGraph checkpoint state |
+| `async def list_checkpoints(...) -> list[dict]` | Optional | List checkpoints for a thread namespace |
+
+> 🚦 *For details on how checkpointer, thread forking, and human-in-the-loop suspension integrate with these storage methods, see the [Advanced Platform Features Guide](platform-features.md).*

{agentomatic-0.1.1 → agentomatic-0.2.0}/docs/index.md

@@ -10,20 +10,20 @@ hide:
     <img src="assets/logo.png" width="300" alt="agentomatic logo">
   </p>
   
-  <h3>Drop agents, not code. ⚡</h3>
+  <h3>Drop agents, not code. :octicons-zap-24:</h3>
   <p><b>The zero-code multi-agent API platform framework.</b> Turn any agent script or graph into a secure, resilient, enterprise-grade microservice with auto-discovery, SSE streaming, thread persistence, and prompt optimization — in 3 lines of code.</p>
 
   <p>
     <a href="https://pypi.org/project/agentomatic/"><img src="https://img.shields.io/pypi/v/agentomatic.svg" alt="PyPI version"></a>
     <img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python 3.11+">
     <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License: MIT">
-    <img src="https://img.shields.io/badge/tests-161%20passing-brightgreen.svg" alt="Tests passing">
+    <img src="https://img.shields.io/badge/tests-175%20passing-brightgreen.svg" alt="Tests passing">
   </p>
 </div>
 
 ---
 
-## ⚡ What is Agentomatic?
+## :octicons-zap-24: What is Agentomatic?
 
 **Agentomatic** acts as a production-ready application server for AI agents. Whether you write raw Python functions, build complex multi-agent orchestrations with **LangGraph**, or chain tools together with **LangChain**, Agentomatic auto-discovers your code and mounts a complete FastAPI application with standard REST routes, server-sent events (SSE) streaming, database adapters, telemetry, and rate limiting.
 
@@ -41,41 +41,41 @@ Run with `uvicorn main:app --reload` and visit `/docs` for a fully documented Op
 
 ---
 
-## 🏗️ Platform Architecture
+## :material-sitemap: Platform Architecture
 
-Agentomatic's core principle is **Convention over Configuration**. By dividing agents into isolated directories containing a manifest, configuration, and a execution graph, the framework automatically maps directory files to API endpoints, database adapters, and prompt templates.
+Agentomatic's core principle is **Convention over Configuration**. By dividing agents into isolated directories containing a manifest, configuration, and an execution graph, the framework automatically maps directory files to API endpoints, database adapters, and prompt templates.
 
 ![Agentomatic Architecture](assets/architecture_diagram.png)
 
 ---
 
-## 🚀 Key Features
+## :octicons-star-fill-24: Key Features
 
-### 🔍 1. Auto-Discovery & Hot Reloading
+### :material-flash: 1. Auto-Discovery & Hot Reloading
 Drop a directory containing an `__init__.py` file (which exports an `AgentManifest` and execution function) into your `agents/` folder. Agentomatic automatically spins up a custom FastAPI router, parses your input/output schemas, and mounts a complete suite of **12+ REST endpoints** for that specific agent.
 
-### 🌊 2. Synchronous & SSE Streaming
+### :material-waves: 2. Synchronous & SSE Streaming
 Standardize how clients talk to your agents. Every agent gets a synchronous `/invoke` endpoint and an asynchronous `/invoke/stream` Server-Sent Events (SSE) streaming endpoint that streams intermediate agent thought steps, tool calls, and final answers in real-time.
 
-### 🗄️ 3. Session-Aware Chat & Persistence
+### :material-database: 3. Session-Aware Chat & Persistence
 The `/chat` endpoint manages full context history automatically. By passing a `thread_id`, Agentomatic reads the conversation log, formats it as history, and executes your agent. Swappable database adapters (**MemoryStore**, **SQLAlchemyStore**) let you persist user messages to PostgreSQL, MySQL, or SQLite out of the box.
 
-### 🛡️ 4. Enterprise-Grade Middleware
+### :material-shield-key: 4. Enterprise-Grade Middleware
 Keep your agents safe and monitored. Toggle middleware filters globally or per-agent:
 - **API Key Auth**: Secured endpoints with customizable key authorization.
 - **Token Bucket Rate Limiting**: Prevent abuse by limiting queries per IP/User.
 - **Prometheus Metrics**: Monitor latency, request counts, and active connections at `/metrics`.
 - **Structured Logging**: Context-scoped loguru logs tracking execution durations and exceptions.
 
-### 📊 5. Prompt Tuning & Optimization (DSPy-inspired)
+### :material-tune-vertical: 5. Prompt Tuning & Optimization (DSPy-inspired)
 Tune prompts like hyper-parameters. Agentomatic includes a prompt optimization module with **7 optimization strategies** (e.g. `iterative_rewrite`, `few_shot_bootstrap`) and **8 evaluation metrics** (answer relevancy, faithfulness, toxic speech check, etc.). Generate synthetic datasets with a single command and track prompt version history with side-by-side HTML reports.
 
-### 🎨 6. ChatGPT-like Debug UI
+### :material-palette: 6. ChatGPT-like Debug UI
 No frontend development required. Run `agentomatic run --with-ui` to launch a built-in, production-quality **Chainlit** chat interface where you can test agents, select prompt versions, inspect step-by-step tool invocations, and submit feedback ratings.
 
 ---
 
-## 🗺️ How does it compare?
+## :material-swap-horizontal: How does it compare?
 
 | Feature | Raw FastAPI + LangChain | Agentomatic Platform |
 | :--- | :--- | :--- |
@@ -88,7 +88,7 @@ No frontend development required. Run `agentomatic run --with-ui` to launch a bu
 
 ---
 
-## 🏁 Quick Installation
+## :material-download: Quick Installation
 
 Install Agentomatic and all its production components (including optimizer and web UI) using `pip` or `uv`:
 
@@ -102,7 +102,7 @@ uv add agentomatic --extra all
 
 ---
 
-## 🛠️ Create Your First Agent
+## :material-play: Create Your First Agent
 
 Scaffold a basic chatbot and start the local API platform with two terminal commands:
 

{agentomatic-0.1.1 → agentomatic-0.2.0}/mkdocs.yml

@@ -90,6 +90,7 @@ nav:
     - Configuration: guide/configuration.md
     - Storage Backends: guide/storage.md
     - Middleware: guide/middleware.md
+    - Advanced Platform Features: guide/platform-features.md
     - Prompt Optimization: guide/optimization.md
     - Telemetry & Feedback: guide/telemetry.md
     - Debug UI: guide/debug-ui.md

{agentomatic-0.1.1 → agentomatic-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentomatic"
-version = "0.1.1"
+version = "0.2.0"
 description = "Drop agents, not code — zero-code multi-agent API platform framework"
 readme = "README.md"
 license = {text = "MIT"}
@@ -81,6 +81,7 @@ Changelog = "https://github.com/UnicoLab/agentomatic/blob/main/CHANGELOG.md"
 
 
 
+
 [dependency-groups]
 dev = [
     "pytest>=8",

{agentomatic-0.1.1 → agentomatic-0.2.0}/src/agentomatic/_version.py

@@ -2,4 +2,4 @@
 
 from __future__ import annotations
 
-__version__ = "0.1.1"
+__version__ = "0.2.0"

{agentomatic-0.1.1 → agentomatic-0.2.0}/src/agentomatic/core/platform.py

@@ -171,6 +171,14 @@ class AgentPlatform:
         """Set the storage backend."""
         self._store = value
 
+    def register_before_node_hook(self, hook: Callable[[str, dict[str, Any]], None]) -> None:
+        """Register a hook to execute before any agent node/graph runs."""
+        self._registry.before_node_hooks.append(hook)
+
+    def register_after_node_hook(self, hook: Callable[[str, dict[str, Any]], None]) -> None:
+        """Register a hook to execute after any agent node/graph runs."""
+        self._registry.after_node_hooks.append(hook)
+
     # ------------------------------------------------------------------
     # Programmatic registration
     # ------------------------------------------------------------------

{agentomatic-0.1.1 → agentomatic-0.2.0}/src/agentomatic/core/registry.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import importlib
+from collections.abc import Callable
 from pathlib import Path
 from typing import Any
 
@@ -25,6 +26,8 @@ class AgentRegistry:
 
     def __init__(self) -> None:
         self._agents: dict[str, RegisteredAgent] = {}
+        self.before_node_hooks: list[Callable[[str, dict[str, Any]], None]] = []
+        self.after_node_hooks: list[Callable[[str, dict[str, Any]], None]] = []
 
     @property
     def count(self) -> int: