agentomatic 0.1.0__tar.gz → 0.2.0__tar.gz

{agentomatic-0.1.0 → agentomatic-0.2.0}/.github/workflows/ci.yml

@@ -1,5 +1,8 @@
 name: CI
 
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
 on:
   push:
     branches: [main]

{agentomatic-0.1.0 → agentomatic-0.2.0}/.github/workflows/docs.yml

@@ -1,5 +1,8 @@
 name: Docs
 
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
 on:
   push:
     branches: [main]

{agentomatic-0.1.0 → agentomatic-0.2.0}/.github/workflows/manual-docs.yml

@@ -1,5 +1,8 @@
 name: "Manual Documentation Publish"
 
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
 on:
   workflow_dispatch:
     inputs:

{agentomatic-0.1.0 → agentomatic-0.2.0}/.github/workflows/manual-pypi.yml

@@ -1,5 +1,8 @@
 name: "Manual PyPI Publish"
 
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
 on:
   workflow_dispatch:
     inputs:
@@ -48,6 +51,7 @@ jobs:
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           password: ${{ secrets.PYPI_TOKEN }}
+          attestations: false
         continue-on-error: true
 
       - name: Retry PyPI publish on failure
@@ -63,3 +67,4 @@ jobs:
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           password: ${{ secrets.PYPI_TOKEN }}
+          attestations: false

{agentomatic-0.1.0 → agentomatic-0.2.0}/.github/workflows/pr-checks.yml

@@ -1,5 +1,8 @@
 name: PR Checks
 
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
 on:
   pull_request:
     branches: [main]

{agentomatic-0.1.0 → agentomatic-0.2.0}/.github/workflows/release.yml

@@ -1,5 +1,8 @@
 name: Release
 
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
 on:
   workflow_dispatch:
     inputs:
@@ -91,6 +94,7 @@ jobs:
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           password: ${{ secrets.PYPI_TOKEN }}
+          attestations: false
         continue-on-error: true
 
       - name: Retry PyPI publish on failure
@@ -106,6 +110,7 @@ jobs:
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           password: ${{ secrets.PYPI_TOKEN }}
+          attestations: false
 
   # ─────────────────────────────────────────────────────────────
   # 3. GITHUB RELEASE — Create GitHub release with assets

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

@@ -1,6 +1,56 @@
 # 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
+
+- Resolve import block sorting and unused typing imports
+  ([`99c83ba`](https://github.com/UnicoLab/agentomatic/commit/99c83ba9c0170a29584db4dca316999f764a4c13))
+
+- **ci**: Force Node.js 24 runtime and disable PyPI attestations to remove warnings
+  ([`275a233`](https://github.com/UnicoLab/agentomatic/commit/275a2336cbfe8ca6860e95545172d02ff118234e))
+
+### Documentation
+
+- Add detailed input and output schemas guide and improve custom schema extraction
+  ([`4c5e079`](https://github.com/UnicoLab/agentomatic/commit/4c5e0790aeaf68cfcbe6f0f0c52963c9ce3bdffe))
+
+- Expand agent structure, customization overrides, and platform settings references
+  ([`5aa9956`](https://github.com/UnicoLab/agentomatic/commit/5aa9956f25f2a56abf27d364f56f086d4a105616))
+
+- Overhaul documentation with detailed guides, visual diagrams, and logo accents
+  ([`ef3de5a`](https://github.com/UnicoLab/agentomatic/commit/ef3de5adb9056184b4a66e7c7130c673c84088e6))
+
+- **agnostic**: Replace all remaining hr_bot references with project-agnostic placeholders
+  ([`4f868d6`](https://github.com/UnicoLab/agentomatic/commit/4f868d623362d6fa0e1e961cccf52440df4d4aa4))
+
+- **prompts**: Document versioned prompts and PromptManager usage
+  ([`f0fe872`](https://github.com/UnicoLab/agentomatic/commit/f0fe8726d73cafd935afa67724b427f452c6d33c))
+
+
 ## v0.1.0 (2026-06-13)
 
 ### Bug Fixes

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentomatic
-Version: 0.1.0
+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/cli/commands.md

@@ -0,0 +1,285 @@
+# CLI Reference
+
+<div align="center">
+  <img src="../assets/logo.png" width="200" alt="agentomatic logo">
+  <h3>Interactive Command-Line Toolchain</h3>
+</div>
+
+---
+
+Agentomatic ships with a robust, click-based CLI for scaffolding, serving, listing, inspecting, testing, and optimizing your agents.
+
+---
+
+## ⚡ Global Help Overview
+
+```bash
+agentomatic --help
+```
+
+```text
+Usage: agentomatic [OPTIONS] COMMAND [ARGS]...
+
+  Agentomatic — Drop agents, not code ⚡
+
+Options:
+  --version  Show the version and exit.
+  --help     Show this message and exit.
+
+Commands:
+  init      Scaffold a new agent from a template.
+  run       Start the platform server.
+  list      List discovered agents.
+  test      Interactive agent testing in the console.
+  inspect   Show agent folder structure and configs.
+  doctor    Verify environment health and packages.
+  ui        Launch the Chainlit debug UI.
+  optimize  Run automatic prompt tuning loops.
+```
+
+---
+
+## 🏗️ `agentomatic init`
+
+Scaffold a new agent directory from one of our 5 pre-built conventions.
+
+### Usage
+```text
+Usage: agentomatic init [OPTIONS] NAME
+
+Arguments:
+  NAME  Agent name (snake_case)  [required]
+
+Options:
+  -t, --template [basic|full|rag|chatbot|custom]
+                          Template to use (interactive list if omitted)
+  --dir TEXT              Agents parent directory  [default: agents]
+  -f, --force             Overwrite existing agent directory
+```
+
+### Examples
+```bash
+# Select templates interactively (requires pip install questionary)
+agentomatic init support_agent
+
+# Standard scaffolding (basic template)
+agentomatic init helper_bot --template basic
+
+# RAG template forced overwrite
+agentomatic init knowledge_bot --template rag --force
+```
+
+---
+
+## 🚀 `agentomatic run`
+
+Start the platform microservice. Runs a local `uvicorn` web server hosting the FastAPI routing stack.
+
+### Usage
+```text
+Usage: agentomatic run [OPTIONS]
+
+Options:
+  --agents-dir TEXT  Agents folder to scan  [default: agents]
+  --host TEXT        Bind address  [default: 0.0.0.0]
+  --port INTEGER     Bind port  [default: 8000]
+  --reload           Auto-reload on code or config file changes
+  --with-ui          Mount the Chainlit chat UI at /chat
+```
+
+### Examples
+```bash
+# Standard launch
+agentomatic run
+
+# Dev launch (live reload + debugging Chat UI at http://localhost:8000/chat)
+agentomatic run --reload --with-ui
+
+# Bound to specific port
+agentomatic run --port 9000
+```
+
+---
+
+## 📊 `agentomatic list`
+
+Scans your agents folder and prints a rich table of discovered agent packages and their statuses.
+
+### Usage
+```text
+Usage: agentomatic list [OPTIONS]
+
+Options:
+  --agents-dir TEXT  Agents folder to scan  [default: agents]
+```
+
+### Example Output
+```text
+╭────────────────────── Discovered Agents ──────────────────────╮
+│ Name         │ Framework  │ Version │ Endpoints │ Status      │
+├──────────────┼────────────┼─────────┼───────────┼─────────────┤
+│ my_agent     │ langgraph  │ 1.0.0   │ 12        │ Ready       │
+│ rag_agent    │ langgraph  │ 1.0.0   │ 12        │ Ready       │
+│ classifier   │ custom     │ 0.1.0   │ 12        │ Ready       │
+╰──────────────┴────────────┴─────────┴───────────┴─────────────╯
+```
+
+---
+
+## 🔍 `agentomatic inspect`
+
+Validates your agent package structure, reading manifest properties and listing present/absent conventions.
+
+### Usage
+```text
+Usage: agentomatic inspect [OPTIONS] NAME
+
+Arguments:
+  NAME  Agent name to inspect  [required]
+
+Options:
+  --agents-dir TEXT  Agents parent folder  [default: agents]
+```
+
+### Example Output
+```text
+╭──────────────────── Agent: my_agent ──────────────────╮
+│ Manifest                                              │
+│   name:        my_agent                               │
+│   slug:        my-agent                               │
+│   framework:   langgraph                              │
+│   version:     1.0.0                                  │
+│   keywords:    help, search, assistant                │
+│                                                       │
+│ Files                                                 │
+│   ✅ __init__.py    (manifest + entry)                │
+│   ✅ graph.py       (state graph)                     │
+│   ✅ nodes.py       (processing logic)                │
+│   ✅ config.py      (pydantic config)                 │
+│   ✅ prompts.json   (2 versions: v1, v2)              │
+│   ⬚  api.py        (not present — using auto-gen)    │
+╰───────────────────────────────────────────────────────╯
+```
+
+---
+
+## 💬 `agentomatic test`
+
+Interactive, chat-like terminal interface to test agent completions and streaming directly inside your shell.
+
+### Usage
+```text
+Usage: agentomatic test [OPTIONS] NAME
+
+Arguments:
+  NAME  Agent name to test  [required]
+
+Options:
+  --host TEXT      Server host address  [default: localhost]
+  --port INTEGER   Server host port  [default: 8000]
+```
+
+### Example Session
+```bash
+agentomatic test my_agent
+# 🤖 Connected to my_agent at http://localhost:8000
+# You: Hello!
+# my_agent: Hello! How can I assist you today?
+# You: /quit
+```
+
+---
+
+## 🎯 `agentomatic optimize`
+
+Executes the prompt optimization tuning loop over a dataset, evaluating outputs and saving improvements.
+
+### Usage
+```text
+Usage: agentomatic optimize [OPTIONS] AGENT
+
+Arguments:
+  AGENT  Agent name to optimize  [required]
+
+Options:
+  -d, --dataset TEXT      Path to evaluation dataset (JSONL/CSV)  [required]
+  -m, --metrics TEXT      Comma-separated metrics (e.g., exact_match,contains)  [required]
+  -s, --strategy [iterative_rewrite|few_shot|chain_of_thought]
+                          Optimization strategy  [default: iterative_rewrite]
+  --max-iterations INTEGER
+                          Maximum optimization steps  [default: 10]
+  --target-score FLOAT    Stop optimization once this average score is hit  [default: 0.9]
+  --rewrite-llm TEXT      Override LLM used to rewrite prompt instructions
+  --eval-llm TEXT         Override LLM used to grade responses
+  --llm TEXT              Default LLM to fallback on  [default: ollama/mistral:7b]
+  --patience INTEGER      Stop early if score doesn't improve for N steps  [default: 3]
+  --prompt TEXT           Initial system prompt override (bypasses prompts.json)
+  --no-report             Skip generating interactive HTML report logs
+  --apply                 Automatically save and promote the best-performing prompt
+  --host TEXT             Platform API base host url  [default: http://localhost:8000]
+```
+
+### Examples
+```bash
+# Run basic optimization loop and auto-save the best prompt
+agentomatic optimize my_agent \
+  --dataset eval_qa.jsonl \
+  --metrics exact_match,contains \
+  --strategy iterative_rewrite \
+  --max-iterations 10 \
+  --apply
+```
+
+---
+
+## 🩺 `agentomatic doctor`
+
+Diagnostic diagnostic tool that audits your local Python virtualenv, installs, dependencies, package versions, and external service connections (Ollama / OpenAI).
+
+### Usage
+```text
+Usage: agentomatic doctor [OPTIONS]
+
+Options:
+  --agents-dir TEXT  Agents folder to inspect  [default: agents]
+```
+
+### Example Output
+```text
+╭──────────────────── Agentomatic Doctor ────────────────────╮
+│ ✅ Python         3.12.0                                   │
+│ ✅ agentomatic    0.1.0                                    │
+│ ✅ FastAPI        0.115.x                                  │
+│ ✅ click          8.1.x                                    │
+│ ✅ LangGraph      0.4.x                                   │
+│ ✅ Ollama         connected                                │
+│ ⬚  OpenAI        not installed                             │
+│ ✅ Prometheus     0.21.x                                   │
+│ ✅ SQLAlchemy     2.0.x                                    │
+│ ✅ Chainlit       2.0.x                                    │
+│ ✅ DeepEval       2.0.x                                    │
+│ ✅ OpenTelemetry  1.20.x                                   │
+╰────────────────────────────────────────────────────────────╯
+```
+
+---
+
+## 🎨 `agentomatic ui`
+
+Launch the Chainlit debug Chat console as a standalone process (points to a running backend application).
+
+### Usage
+```text
+Usage: agentomatic ui [OPTIONS]
+
+Options:
+  --host TEXT        FastAPI server address  [default: localhost]
+  --port INTEGER     FastAPI server port  [default: 8000]
+  --ui-port INTEGER  Chainlit UI port to bind  [default: 8001]
+```
+
+### Example
+```bash
+# Launch standalone debug UI on port 9000
+agentomatic ui --port 8000 --ui-port 9000
+```

agentomatic-0.2.0/docs/getting-started/first-agent.md

@@ -0,0 +1,135 @@
+# Your First Agent
+
+<div align="center">
+  <img src="../assets/logo.png" width="200" alt="agentomatic logo">
+  <h3>Step-by-Step RAG Agent Tutorial</h3>
+</div>
+
+---
+
+This tutorial walks through building a production-ready **Retrieval-Augmented Generation (RAG)** search agent from scratch using Agentomatic.
+
+---
+
+## Step 1: Scaffold the Agent Folder
+
+Use the `full` scaffolding template to include all optional configuration files and overrides:
+
+```bash
+agentomatic init search_bot --template full
+```
+
+This creates a dedicated directory containing:
+
+```text
+agents/search_bot/
+├── __init__.py      # Required: agent manifest declaration and entry point
+├── graph.py         # Optional: LangGraph orchestration flow
+├── nodes.py         # Optional: node execution logic
+├── config.py        # Optional: agent settings schema (Pydantic)
+├── schemas.py       # Optional: custom request/response validation schemas
+├── tools.py         # Optional: LangChain tools
+├── api.py           # Optional: custom routers (overrides auto-generated endpoints)
+├── prompts.json     # Optional: versioned prompt templates
+├── langgraph.json   # Optional: local developer environment settings
+├── .env.example     # Optional: environment blueprint
+└── README.md        # Optional: agent readme documentation
+```
+
+---
+
+## Step 2: Declare the Agent Manifest
+
+Open `agents/search_bot/__init__.py`. Define your manifest properties:
+
+```python
+from agentomatic import AgentManifest
+from .graph import get_graph
+
+manifest = AgentManifest(
+    name="search_bot",
+    slug="search-bot",
+    description="Knowledge base search assistant utilizing LangGraph and Vector Stores.",
+    intent_keywords=["search", "find", "document", "knowledge"],
+    version="1.0.0",
+    framework="langgraph",
+)
+
+def graph_fn():
+    """Retrieve the LangGraph compiled state graph."""
+    return get_graph()
+```
+
+---
+
+## Step 3: Implement RAG Nodes
+
+Open `agents/search_bot/nodes.py`. Define your document retrieval and answer generation logic:
+
+```python
+from typing import Any
+from langchain_ollama import ChatOllama
+from langchain_core.messages import HumanMessage
+
+async def retrieve_context(state: dict[str, Any]) -> dict[str, Any]:
+    """Mock document retriever node."""
+    query = state.get("current_query", "")
+    logger_info = f"Querying KB: {query}"
+    
+    # Mock retrieval docs (swap with a real VectorDB like Qdrant/Chroma)
+    docs = [
+        "Company policy: Employees get 25 days of paid time off per year.",
+        "Requesting leaves: Submit request in employee portal 2 weeks in advance."
+    ]
+    return {
+        "citations": [{"source": "company_handbook.pdf", "page": 10}],
+        "metadata": {"retrieved_docs": docs},
+        "steps_taken": ["retrieve_docs"],
+    }
+
+async def generate_response(state: dict[str, Any]) -> dict[str, Any]:
+    """Generates the final response based on retrieved docs."""
+    query = state.get("current_query", "")
+    context = state.get("metadata", {}).get("retrieved_docs", [])
+    
+    # Format a prompt template and query the LLM
+    llm = ChatOllama(model="mistral:7b", temperature=0.1)
+    prompt = f"Context:\n" + "\n".join(context) + f"\n\nQuestion: {query}"
+    
+    result = await llm.ainvoke([HumanMessage(content=prompt)])
+    
+    return {
+        "response": result.content,
+        "suggestions": ["How to request leaves?", "PTO balance check"],
+        "steps_taken": ["generate_response"],
+    }
+```
+
+---
+
+## Step 4: Configure Settings Schema
+
+Open `agents/search_bot/config.py`. Define default agent settings and hyper-parameters using Pydantic:
+
+```python
+from pydantic import BaseModel, Field
+
+class SearchBotConfig(BaseModel):
+    prompt_version: str = Field("v1", description="Default prompt version")
+    temperature: float = Field(0.2, description="Sampling temperature")
+    max_tokens: int = Field(2048, description="Maximum completion tokens")
+    vector_store_url: str = Field("http://localhost:6333", description="Vector database URL")
+```
+
+---
+
+## Step 5: Test the Agent
+
+Start the platform server locally, loading your newly created agent:
+
+```bash
+agentomatic run --reload --with-ui
+```
+
+1. **REST API endpoints**: Go to `http://localhost:8000/docs` to test `/api/v1/search_bot/invoke` interactively.
+2. **Graphical Sandbox**: Go to `http://localhost:8000/chat` to test token-by-token streaming and rating collection.