agentomatic 0.2.0__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,14 @@
 # CHANGELOG
 
 
+## v0.3.0 (2026-06-14)
+
+### Features
+
+- Implement memory management, platform features, and router updates
+  ([`5cf8aa8`](https://github.com/UnicoLab/agentomatic/commit/5cf8aa88ef750e2fa443948981aad2f1f9f1f9c4))
+
+
 ## v0.2.0 (2026-06-14)
 
 ### Documentation

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentomatic
-Version: 0.2.0
+Version: 0.3.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
@@ -132,7 +132,7 @@ Create production-ready AI agent APIs with auto-discovery, auto-routing, streami
 | Feature | Description |
 |---|---|
 | 🔍 **Auto-Discovery** | Drop an agent folder → endpoints appear automatically |
-| 🚀 **12+ Endpoints Per Agent** | invoke, stream, chat, A2A, health, config, threads |
+| 🚀 **25+ Endpoints Per Agent** | invoke, stream, chat, A2A, health, config, threads, memory, feedback |
 | 🗄️ **Pluggable Storage** | MemoryStore, SQLAlchemy, or bring your own |
 | 🔐 **Middleware Pipeline** | Auth, rate limiting, Prometheus metrics — all toggleable |
 | 🎨 **Built-in Debug UI** | ChatGPT-like interface via Chainlit |
@@ -143,6 +143,17 @@ Create production-ready AI agent APIs with auto-discovery, auto-routing, streami
 | ⚡ **Prompt Optimizer** | DSPy-inspired prompt optimization (7 strategies) |
 | 🧪 **Data Synthesizer** | Auto-generate & augment eval datasets via LLM |
 | 📊 **HTML Reports** | SVG charts, prompt diffs, experiment tracking |
+| 🚦 **Human-in-the-Loop** | Suspend/resume execution with human approval gates |
+| 🌳 **Thread Lineage** | First-class parent/child tracking with ancestry traversal |
+| ⏰ **HITL TTL Expiry** | Auto-cleanup of stale suspended states (7-day default) |
+| 🛡️ **LLM Failover** | Multi-provider fallback chains with telemetry |
+| 🧬 **Thread Forking** | Clone conversations at any message index |
+| 🔀 **A/B Prompt Routing** | Weight-based prompt version selection |
+| 🪝 **State Hooks** | Before/after node interceptors for audit & telemetry |
+| 🧠 **Conversation Memory** | Automatic session + long-term memory with windowing |
+| 📝 **Auto-Summarization** | LLM-powered compression of long conversations |
+| 📋 **Thread CRUD** | Full thread lifecycle management (create/update/delete/clear) |
+| 💬 **Message Persistence** | Every turn auto-saved — history survives restarts |
 
 ## 🚀 Quick Start
 
@@ -317,6 +328,11 @@ Every agent gets 12+ endpoints automatically:
 | `GET` | `/api/v1/{agent}/card` | A2A agent card |
 | `POST` | `/api/v1/{agent}/a2a/tasks` | A2A task submission |
 | `GET` | `/api/v1/{agent}/threads` | List threads |
+| `POST` | `/api/v1/{agent}/threads/{id}/approve` | HITL: approve suspended state |
+| `POST` | `/api/v1/{agent}/threads/{id}/reject` | HITL: reject suspended state |
+| `GET` | `/api/v1/{agent}/threads/{id}/pending` | HITL: list pending approvals |
+| `POST` | `/api/v1/{agent}/threads/{id}/fork` | Fork thread at message index |
+| `GET` | `/api/v1/{agent}/threads/{id}/lineage` | Thread ancestry/descendant tree |
 | ... | ... | + config, prompts, thread messages |
 
 ## 🛠️ Development

{agentomatic-0.2.0 → agentomatic-0.3.0}/README.md

@@ -28,7 +28,7 @@ Create production-ready AI agent APIs with auto-discovery, auto-routing, streami
 | Feature | Description |
 |---|---|
 | 🔍 **Auto-Discovery** | Drop an agent folder → endpoints appear automatically |
-| 🚀 **12+ Endpoints Per Agent** | invoke, stream, chat, A2A, health, config, threads |
+| 🚀 **25+ Endpoints Per Agent** | invoke, stream, chat, A2A, health, config, threads, memory, feedback |
 | 🗄️ **Pluggable Storage** | MemoryStore, SQLAlchemy, or bring your own |
 | 🔐 **Middleware Pipeline** | Auth, rate limiting, Prometheus metrics — all toggleable |
 | 🎨 **Built-in Debug UI** | ChatGPT-like interface via Chainlit |
@@ -39,6 +39,17 @@ Create production-ready AI agent APIs with auto-discovery, auto-routing, streami
 | ⚡ **Prompt Optimizer** | DSPy-inspired prompt optimization (7 strategies) |
 | 🧪 **Data Synthesizer** | Auto-generate & augment eval datasets via LLM |
 | 📊 **HTML Reports** | SVG charts, prompt diffs, experiment tracking |
+| 🚦 **Human-in-the-Loop** | Suspend/resume execution with human approval gates |
+| 🌳 **Thread Lineage** | First-class parent/child tracking with ancestry traversal |
+| ⏰ **HITL TTL Expiry** | Auto-cleanup of stale suspended states (7-day default) |
+| 🛡️ **LLM Failover** | Multi-provider fallback chains with telemetry |
+| 🧬 **Thread Forking** | Clone conversations at any message index |
+| 🔀 **A/B Prompt Routing** | Weight-based prompt version selection |
+| 🪝 **State Hooks** | Before/after node interceptors for audit & telemetry |
+| 🧠 **Conversation Memory** | Automatic session + long-term memory with windowing |
+| 📝 **Auto-Summarization** | LLM-powered compression of long conversations |
+| 📋 **Thread CRUD** | Full thread lifecycle management (create/update/delete/clear) |
+| 💬 **Message Persistence** | Every turn auto-saved — history survives restarts |
 
 ## 🚀 Quick Start
 
@@ -213,6 +224,11 @@ Every agent gets 12+ endpoints automatically:
 | `GET` | `/api/v1/{agent}/card` | A2A agent card |
 | `POST` | `/api/v1/{agent}/a2a/tasks` | A2A task submission |
 | `GET` | `/api/v1/{agent}/threads` | List threads |
+| `POST` | `/api/v1/{agent}/threads/{id}/approve` | HITL: approve suspended state |
+| `POST` | `/api/v1/{agent}/threads/{id}/reject` | HITL: reject suspended state |
+| `GET` | `/api/v1/{agent}/threads/{id}/pending` | HITL: list pending approvals |
+| `POST` | `/api/v1/{agent}/threads/{id}/fork` | Fork thread at message index |
+| `GET` | `/api/v1/{agent}/threads/{id}/lineage` | Thread ancestry/descendant tree |
 | ... | ... | + config, prompts, thread messages |
 
 ## 🛠️ Development

{agentomatic-0.2.0 → agentomatic-0.3.0}/docs/guide/configuration.md

@@ -37,6 +37,8 @@ platform = AgentPlatform.from_folder(
     enable_metrics=True,
     enable_feedback=True,
     enable_telemetry=True,
+    max_history_messages=50,
+    summarize_after=30,
 )
 ```
 
@@ -62,9 +64,17 @@ platform = AgentPlatform.from_folder(
 
 ### 4. Storage Backend
 
-- **`store`** (type: `BaseStore | None`, default: `None`): Instance of a storage adapter (e.g. `MemoryStore` or `SQLAlchemyStore`) used to save message threads and rating logs.
+- **`store`** (type: `BaseStore | None`, default: `None`): Instance of a storage adapter (e.g. `MemoryStore` or `SQLAlchemyStore`) used to save message threads, conversation history, and rating logs.
 
-### 5. Security & Rate Limiting
+### 5. Memory & Conversation
+
+- **`max_history_messages`** (type: `int`, default: `50`): Maximum number of messages to load from the thread store into the agent's context window. When the conversation exceeds this limit, older messages are windowed out or summarised.
+- **`summarize_after`** (type: `int`, default: `30`): When the message count in a thread exceeds this threshold, older messages are automatically summarised using the configured LLM and prepended as a `[Conversation Summary]` system message.
+
+> [!TIP]
+> These values can also be overridden per-request using the `max_history` field on `AgentChatRequest`, giving frontends full control over how much context each invocation receives.
+
+### 6. Security & Rate Limiting
 
 - **`enable_auth`** (type: `bool`, default: `False`): If `True`, mounts Key Authentication middleware on all agent routes.
 - **`auth_api_key`** (type: `str`, default: `""`): The secret API key token required by clients when `enable_auth` is enabled.

{agentomatic-0.2.0 → agentomatic-0.3.0}/docs/guide/platform-features.md

@@ -337,3 +337,353 @@ def audit_output_hook(agent_name: str, result: dict):
 
 platform.register_after_node_hook(audit_output_hook)
 ```
+
+---
+
+## 🛡️ 8. Safe Checkpoint Serialization
+
+LangGraph checkpoints can contain non-JSON-serializable Python objects (datetimes, bytes, custom classes). The `AgentomaticCheckpointer` automatically handles this via a safe JSON round-trip:
+
+```python
+from agentomatic.storage.checkpointer import AgentomaticCheckpointer, _ensure_json_serializable
+
+# Objects like datetimes, bytes, and custom classes are safely converted
+data = _ensure_json_serializable({"ts": datetime.now(), "raw": b"bytes"})
+# → {"ts": "2026-06-14 12:00:00", "raw": "b'bytes'"}
+```
+
+This happens transparently inside `aput()` — no user configuration needed. All values are round-tripped through `json.dumps(obj, default=str)` → `json.loads()`.
+
+---
+
+## ⏰ 9. HITL TTL Expiry & Cleanup
+
+Suspended states automatically receive a 7-day TTL (`expires_at`). This prevents stale suspended states from accumulating in the database when humans forget to approve or reject them.
+
+### Automatic TTL
+
+When `save_suspended_state()` is called, the `expires_at` field defaults to `now + 7 days`:
+
+```python
+state = await store.save_suspended_state(
+    approval_id="app_xyz",
+    thread_id="thread_1",
+    agent_name="my_agent",
+    node_name="approval_node",
+    state_json={"action": "delete_account"},
+)
+print(state["expires_at"])  # 7 days from now
+```
+
+### Cleanup
+
+Call `cleanup_expired_states()` on a schedule (e.g. cron, background task) to purge expired states:
+
+```python
+# Clean up expired suspended states
+count = await store.cleanup_expired_states()
+print(f"Cleaned up {count} expired states")
+```
+
+This works identically on `MemoryStore` and `SQLAlchemyStore`.
+
+---
+
+## 🌳 10. Thread Lineage Tracking
+
+Forked threads now have **first-class lineage fields** instead of metadata-based tracking:
+
+| Field | Type | Description |
+|---|---|---|
+| `parent_thread_id` | `str \| None` | ID of the parent thread (null for root threads) |
+| `fork_message_index` | `int \| None` | Message index where the fork occurred |
+
+### Querying Lineage
+
+Use `get_thread_lineage()` to traverse the full ancestor/descendant tree:
+
+```python
+# Fork a thread
+forked = await store.fork_thread("root_thread", 2, "child_thread")
+print(forked["parent_thread_id"])  # "root_thread"
+
+# Get full lineage
+lineage = await store.get_thread_lineage("child_thread")
+print(lineage["ancestors"])    # [root_thread_dict]
+print(lineage["descendants"])  # []
+```
+
+### REST Endpoint
+
+```http
+GET /api/v1/{agent}/threads/{thread_id}/lineage
+```
+
+**Response:**
+```json
+{
+  "thread_id": "child_thread",
+  "ancestors": [{"id": "root_thread", ...}],
+  "descendants": [{"id": "grandchild_thread", ...}]
+}
+```
+
+---
+
+## 📊 11. LLM Failover Telemetry
+
+Track failover events for observability and alerting:
+
+```python
+from agentomatic.providers.llm import record_failover, get_failover_count, reset_llm
+
+# Record a failover event
+record_failover("openai", "azure", "RateLimitError")
+# Emits: 🔄 LLM failover #1: openai -> azure | Error: RateLimitError
+
+# Check current count
+print(get_failover_count())  # 1
+
+# Reset (typically in tests)
+reset_llm()  # Also resets failover counter
+```
+
+The failover chain now also passes `exceptions_to_handle=(Exception,)` to `with_fallbacks()`, ensuring **any** exception triggers the fallback chain, not just specific ones.
+
+---
+
+## 🧠 12. Conversation Memory & Session Management
+
+Agentomatic provides **automatic conversation memory** for all deployed agents. When a thread store is configured, every `/chat` and `/invoke` call automatically:
+
+1. **Loads prior conversation history** into the agent's `messages` state
+2. **Invokes the agent** with full conversational context
+3. **Persists** both user and assistant messages to the store
+4. **Summarises** older messages when the conversation grows long
+
+```
+          Frontend                    Agentomatic                    Store
+             │                            │                           │
+             │  POST /chat                │                           │
+             │  {content, thread_id}      │                           │
+             │───────────────────────────>│                           │
+             │                            │  get_messages(thread_id)  │
+             │                            │──────────────────────────>│
+             │                            │  [msg1, msg2, ...]        │
+             │                            │<──────────────────────────│
+             │                            │                           │
+             │                            │  ── Windowing ──          │
+             │                            │  ── Summarization ──      │
+             │                            │                           │
+             │                            │  ainvoke(state)           │
+             │                            │  (state.messages =        │
+             │                            │   history + current)      │
+             │                            │                           │
+             │                            │  add_message(user)        │
+             │                            │──────────────────────────>│
+             │                            │  add_message(assistant)   │
+             │                            │──────────────────────────>│
+             │                            │                           │
+             │  {response, thread_id,     │                           │
+             │   history_loaded: 12}      │                           │
+             │<───────────────────────────│                           │
+```
+
+### Configuration
+
+Memory is automatically enabled when a `store` is provided to `AgentPlatform`:
+
+```python
+from agentomatic import AgentPlatform
+from agentomatic.storage import MemoryStore
+
+platform = AgentPlatform.from_folder(
+    "agents/",
+    store=MemoryStore(),  # enables memory + thread management
+    max_history_messages=50,  # max messages in context window
+    summarize_after=30,       # summarize when exceeding this count
+)
+```
+
+### Chat Request with Memory
+
+```python
+# Frontend sends a message with thread_id
+POST /api/v1/my_agent/chat
+{
+    "content": "What's our PTO policy?",
+    "thread_id": "thread_abc123",   # reuse for multi-turn
+    "user_id": "user_42",
+    "context": {                    # arbitrary data for agent code
+        "user_role": "manager",
+        "department": "engineering"
+    },
+    "include_history": true,        # default: true
+    "max_history": 20,              # optional override
+    "persist": true,                # default: true — auto-save messages
+    "prompt_version": "v1"          # optional explicit prompt version
+}
+```
+
+#### Override: Supply Your Own Messages
+
+If the frontend manages its own conversation state, it can pass `messages` directly — this **skips** automatic history loading from the store:
+
+```python
+POST /api/v1/my_agent/chat
+{
+    "content": "Follow-up question",
+    "messages": [
+        {"role": "user", "content": "Previous question"},
+        {"role": "assistant", "content": "Previous answer"}
+    ],
+    "persist": false    # optional: don't save to store
+}
+```
+
+#### Response
+
+The response includes all agent output fields plus conversation metadata:
+
+```json
+{
+    "response": "Based on our company handbook...",
+    "thread_id": "thread_abc123",
+    "agent_type": "hr-agent",
+    "suggestions": ["Ask about sick days", "View calendar"],
+    "citations": [...],
+    "steps_taken": ["search_policy_db", "generate_response"],
+    "context": {"retrieved_documents": [...]},
+    "duration_ms": 234.5,
+    "metadata": {"prompt_version": "v1", "source": "mobile_app"},
+    "history_loaded": 12
+}
+```
+
+| Response Field | Description |
+|----------------|-------------|
+| `response` | Agent's text response |
+| `thread_id` | Thread ID (auto-created if not provided) |
+| `agent_type` | Agent slug identifier |
+| `suggestions` | Follow-up suggestions from agent |
+| `citations` | Source citations from agent |
+| `steps_taken` | Processing steps the agent took |
+| `context` | Context data returned by agent (RAG docs, search results, etc.) |
+| `metadata` | Merged metadata (request + agent + prompt_version) |
+| `history_loaded` | Number of prior messages loaded into context |
+| `duration_ms` | Processing time in milliseconds |
+
+### Windowing & Summarization
+
+When conversations grow long, agentomatic automatically:
+
+1. **Windows** — keeps only the latest `max_messages` in context
+2. **Summarises** — compresses older messages into a summary via the LLM
+3. **Prepends** — adds `[Conversation Summary]` as a system message
+
+```python
+# Example: After 50 messages, the agent receives:
+state["messages"] = [
+    SystemMessage("[Conversation Summary]\nUser discussed PTO policy..."),
+    HumanMessage("Question 48"),
+    AIMessage("Answer 48"),
+    HumanMessage("Question 49"),
+    AIMessage("Answer 49"),
+    HumanMessage("Current question"),  # ← latest
+]
+```
+
+If no LLM is available, a fallback summary is used (simple truncated concatenation).
+
+### Using `ConversationMemoryManager` Directly
+
+For advanced use cases, you can use the manager directly:
+
+```python
+from agentomatic.core.memory_manager import ConversationMemoryManager
+from agentomatic.storage import MemoryStore
+
+store = MemoryStore()
+mgr = ConversationMemoryManager(
+    store,
+    max_messages=50,
+    summarize_after=30,
+    summary_token_target=200,
+)
+
+# Load history
+thread_id = await mgr.get_or_create_thread("thread_123", "user_1", "my-agent")
+messages = await mgr.load_history(thread_id, "What's the weather?")
+
+# Save a turn
+await mgr.save_turn(thread_id, "What's the weather?", "It's sunny!", agent_name="weather-bot")
+
+# Get full conversation summary
+summary = await mgr.get_conversation_summary(thread_id)
+```
+
+---
+
+## 📋 13. Thread Management API
+
+Agentomatic provides a full CRUD API for conversation threads.
+
+### Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/threads` | Create a thread explicitly |
+| `GET` | `/threads` | List threads (filterable by `user_id`) |
+| `GET` | `/threads/{id}` | Get a specific thread |
+| `PATCH` | `/threads/{id}` | Update thread title/metadata |
+| `DELETE` | `/threads/{id}` | Delete thread and all messages |
+| `GET` | `/threads/{id}/messages` | Get messages with pagination |
+| `DELETE` | `/threads/{id}/messages` | Clear messages (keep thread) |
+| `GET` | `/threads/{id}/summary` | Generate conversation summary |
+| `POST` | `/threads/{id}/fork` | Fork thread at a message index |
+| `GET` | `/threads/{id}/lineage` | Get thread ancestry tree |
+
+### Examples
+
+```python
+# Create a thread
+POST /api/v1/my_agent/threads
+{"user_id": "user_42", "title": "Onboarding questions"}
+
+# Get paginated messages
+GET /api/v1/my_agent/threads/thread_abc/messages?limit=20&offset=0
+
+# Clear conversation history
+DELETE /api/v1/my_agent/threads/thread_abc/messages
+
+# Update thread title
+PATCH /api/v1/my_agent/threads/thread_abc
+{"title": "Updated title"}
+
+# Get conversation summary
+GET /api/v1/my_agent/threads/thread_abc/summary
+# → {"thread_id": "thread_abc", "summary": "User asked about..."}
+```
+
+### Frontend Integration Guide
+
+For frontend applications (React, Vue, mobile), here's the recommended flow:
+
+```
+1. Start Session
+   POST /threads → get thread_id
+
+2. Send Messages
+   POST /chat {content, thread_id} → get response
+
+3. Load History (on page reload)
+   GET /threads/{id}/messages?limit=50 → display messages
+
+4. Clear Conversation
+   DELETE /threads/{id}/messages → reset
+
+5. List User's Conversations
+   GET /threads?user_id=xxx → sidebar list
+```
+
+All thread data is persisted in the configured store (MemoryStore for dev, SQLAlchemyStore for production).

{agentomatic-0.2.0 → agentomatic-0.3.0}/docs/guide/schemas.md

@@ -43,6 +43,73 @@ Agentomatic searches `schemas.py` for class definitions matching one of these na
 
 ---
 
+## 📋 Default Schema Reference
+
+### `AgentInvokeRequest` (default input)
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `query` | `str` | *required* | User query or input |
+| `user_id` | `str` | `"default-user"` | User identifier |
+| `context` | `dict` | `{}` | Additional context — passed to agent as `state["context"]` |
+| `thread_id` | `str \| None` | `None` | Thread ID for conversation continuity |
+| `prompt_version` | `str` | `"v1"` | Prompt version to use |
+| `temperature` | `float \| None` | `None` | Temperature override (0.0–2.0) |
+| `max_tokens` | `int \| None` | `None` | Max tokens override |
+| `metadata` | `dict` | `{}` | Extra metadata |
+
+### `AgentInvokeResponse` (default output)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `response` | `str` | Agent response text |
+| `agent_type` | `str` | Agent slug |
+| `thread_id` | `str \| None` | Thread ID |
+| `suggestions` | `list[str]` | Follow-up suggestions |
+| `citations` | `list[dict]` | Source citations |
+| `steps_taken` | `list[str]` | Processing steps taken |
+| `context` | `Any` | Context data returned by the agent (RAG documents, etc.) |
+| `metadata` | `dict` | Response metadata (includes `prompt_version`) |
+| `duration_ms` | `float` | Processing time in milliseconds |
+
+### `AgentChatRequest` (chat endpoint)
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `content` | `str` | *required* | User message |
+| `user_id` | `str` | `"default-user"` | User identifier |
+| `thread_id` | `str \| None` | `None` | Existing thread ID (auto-created if omitted) |
+| `context` | `dict` | `{}` | Arbitrary context dict for agent code to consume |
+| `metadata` | `dict` | `{}` | Extra metadata |
+| `messages` | `list[dict] \| None` | `None` | Override: supply your own message history (skips auto-loading) |
+| `include_history` | `bool` | `true` | Load conversation history from store |
+| `max_history` | `int \| None` | `None` | Max messages to load (overrides agent default) |
+| `persist` | `bool` | `true` | Auto-save messages to the store after invocation |
+| `prompt_version` | `str` | `"v1"` | Prompt version to use |
+
+### `BaseAgentState` (agent state dict)
+
+This is the TypedDict available in your agent's `node_fn(state)`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `messages` | `list` | LangChain messages (auto-loaded or user-supplied) |
+| `thread_id` | `str` | Thread ID |
+| `user_id` | `str` | User identifier |
+| `current_query` | `str` | The current user query |
+| `context` | `dict` | Arbitrary context from the frontend/caller |
+| `metadata` | `dict` | Request metadata |
+| `prompt_version` | `str` | Resolved prompt version |
+| `response` | `str` | Agent response (set by your code) |
+| `agent_type` | `str` | Agent slug (set by your code) |
+| `suggestions` | `list[str]` | Follow-up suggestions |
+| `citations` | `list[dict]` | Source citations |
+| `steps_taken` | `list[str]` | Processing steps taken |
+| `routing_decision` | `str` | Routing decision (for orchestrators) |
+| `error` | `str \| None` | Error message if any |
+
+---
+
 ## 🛠️ Defining Custom Schemas
 
 To define custom models, simply import Pydantic's `BaseModel` and declare your fields using type annotations and metadata helpers like `Field`.

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

@@ -191,14 +191,18 @@ Every storage adapter implements the following async interface methods:
 | `async def add_message(...) -> dict` | **Required** | Save a new query/response message |
 | `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_feedback(...) -> list[dict]` | Optional | Search feedback records |
+| `async def get_stats() -> dict` | Optional | Return storage statistics (threads, messages, feedback counts) |
+| `async def save_suspended_state(...) -> dict` | Optional | Save execution state for human approval (auto-sets 7-day TTL) |
 | `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 cleanup_expired_states() -> int` | Optional | Delete expired HITL states, returns count removed |
 | `async def fork_thread(...) -> dict \| None` | Optional | Fork a conversation history up to index |
+| `async def get_thread_lineage(id) -> dict` | Optional | Ancestry/descendant tree for a thread |
 | `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.2.0 → agentomatic-0.3.0}/pyproject.toml

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

{agentomatic-0.2.0 → agentomatic-0.3.0}/src/agentomatic/__init__.py

@@ -33,6 +33,7 @@ from agentomatic._version import __version__
 
 # Core public API
 from agentomatic.core.manifest import AgentManifest, RegisteredAgent
+from agentomatic.core.memory_manager import ConversationMemoryManager
 from agentomatic.core.platform import AgentPlatform
 from agentomatic.core.registry import AgentRegistry
 from agentomatic.core.state import BaseAgentState
@@ -48,6 +49,7 @@ __all__ = [
     "RegisteredAgent",
     "AgentRegistry",
     "BaseAgentState",
+    "ConversationMemoryManager",
     # Protocols
     "APIResponse",
     "handle_api_errors",

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

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

{agentomatic-0.2.0 → agentomatic-0.3.0}/src/agentomatic/core/__init__.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 from .lifespan import configure_logging, create_lifespan
 from .manifest import AgentManifest, RegisteredAgent
+from .memory_manager import ConversationMemoryManager
 from .platform import AgentPlatform
 from .registry import AgentRegistry
 from .router_factory import (
@@ -11,6 +12,12 @@ from .router_factory import (
     AgentChatRequest,
     AgentInvokeRequest,
     AgentInvokeResponse,
+    AgentSuspendedException,
+    ApproveSuspendedRequest,
+    CreateThreadRequest,
+    ForkThreadRequest,
+    RejectSuspendedRequest,
+    UpdateThreadRequest,
     create_default_router,
 )
 from .state import BaseAgentState
@@ -23,8 +30,15 @@ __all__ = [
     "AgentManifest",
     "AgentPlatform",
     "AgentRegistry",
+    "AgentSuspendedException",
+    "ApproveSuspendedRequest",
     "BaseAgentState",
+    "ConversationMemoryManager",
+    "CreateThreadRequest",
+    "ForkThreadRequest",
     "RegisteredAgent",
+    "RejectSuspendedRequest",
+    "UpdateThreadRequest",
     "configure_logging",
     "create_default_router",
     "create_lifespan",