icogito 0.1.0__tar.gz

icogito-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.3
+Name: icogito
+Version: 0.1.0
+Summary: A modern Python CLI framework to build Agent/Multi-Agents systems
+Author: Daniel Rondon
+Author-email: Daniel Rondon <hello@danielrondon.com>
+Requires-Dist: graphifyy>=0.9.67
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: pydantic-ai>=2.48.0
+Requires-Dist: pydantic-ai-harness>=0.34.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: questionary>=2.1.1
+Requires-Dist: tavily-python>=0.8.4
+Requires-Dist: typer>=0.27.2
+Requires-Dist: pytest>=8.0.0 ; extra == 'test'
+Requires-Dist: pytest-mock>=3.12.0 ; extra == 'test'
+Requires-Python: >=3.12
+Provides-Extra: test
+Description-Content-Type: text/markdown
+
+# icogito
+
+> A modern Python CLI framework to build Agent/Multi-Agent systems on top of `pydantic-ai`, `pydantic-ai-harness`, OpenRouter, and Tavily tools.
+
+`icogito` provides an end-to-end toolkit for scaffolding, configuring, and running production-grade AI agent and multi-agent architectures. It integrates durable execution via Prefect, modular tool registry integration (including Tavily search, fetch, and crawl tools), and OpenRouter model routing.
+
+---
+
+## Key Features
+
+- **CLI-Driven Scaffolding**: Easily create standardized directory structures (`agents/`, `configs/`, `prompts/`, `schemas/`, `tools/`, `utils/`) using `icogito init`.
+- **Interactive Configuration**: Build single-agent and multi-agent workflow configurations interactively with `icogito configure`.
+- **System Diagnostics**: Verify tools, environment setup, and framework status with `icogito doctor`.
+- **Agent Factory**: Instantiates `pydantic-ai` Agents dynamically from YAML configurations (`AgentConfig`).
+- **Durable Execution & Subagents**: Supports task durability via `PrefectDurability` and hierarchical multi-agent delegation via `SubAgents`.
+- **Built-in Web Tools**: Tavily web integration for search, fetch, and crawl capabilities with built-in retry handling.
+
+---
+
+## Get Started
+
+### Prerequisites
+
+- **Python**: Version `>= 3.12`
+- **uv**: Recommended fast Python package and environment manager ([docs.astral.sh/uv](https://docs.astral.sh/uv/))
+- **API Keys**:
+  - `OPENROUTER_API_KEY`: Required for model inference via OpenRouter.
+  - `TAVILY_API_KEY`: Required when using Tavily web tools (`web_search`, `web_fetch`, `web_crawl`).
+
+### Installation
+
+Clone the repository and install dependencies using `uv`:
+
+```bash
+# Clone the repository
+git clone https://github.com/danielrondon/icogito.git
+cd icogito
+
+# Sync project dependencies into .venv
+uv sync
+
+# (Optional) Sync test extra dependencies if developing or running tests
+uv sync --extra test
+```
+
+### Local Environment Setup
+
+Configure your environment variables before running agent workflows or tools:
+
+```bash
+export OPENROUTER_API_KEY="your-openrouter-api-key"
+export TAVILY_API_KEY="your-tavily-api-key"
+```
+
+---
+
+## Usage
+
+### CLI Commands
+
+The `icogito` CLI provides commands for project initialization, diagnostics, and agent configuration.
+
+#### 1. Initialize Project Scaffolding (`icogito init`)
+
+Scaffold a standard agent directory structure in your project or a target directory:
+
+```bash
+# Initialize scaffolding in the current directory
+uv run icogito init
+
+# Or specify a target directory
+uv run icogito init ./my_agent_project
+```
+
+This creates the following directory layout:
+```
+.
+├── agents/
+├── configs/
+├── prompts/
+├── schemas/
+├── tools/
+└── utils/
+```
+
+#### 2. System Diagnostics (`icogito doctor`)
+
+Check system environment status, global app directory path, available Tavily web tools, and `AgentFactory` readiness:
+
+```bash
+# Run standard diagnostic check
+uv run icogito doctor
+
+# Verbose diagnostic output
+uv run icogito doctor --verbose
+```
+
+#### 3. Interactive Agent Configuration (`icogito configure`)
+
+Interactively configure single or multi-agent systems. This wizard prompts for agent names, OpenRouter models, providers, instructions, enabled tools, and subagents, then generates the corresponding YAML configs in `configs/` and Markdown instructions in `prompts/`:
+
+```bash
+uv run icogito configure
+```
+
+---
+
+### Programmatic Usage
+
+`icogito` provides high-level utilities and `AgentFactory` for loading configs and instantiating runtime agents.
+
+#### Loading Configuration and Instantiating Agents
+
+```python
+import os
+from icogito.factory import AgentFactory
+from icogito.utils.load_agent_config import load_agent_config
+
+# Load agent configuration from YAML
+config = load_agent_config("configs/research_agent_config.yaml")
+
+# Initialize AgentFactory with your OpenRouter API Key
+factory = AgentFactory(openrouter_api_key=os.getenv("OPENROUTER_API_KEY"))
+
+# Create a pydantic-ai Agent instance
+agent = factory.create_agent(config)
+
+# Run the agent (async)
+# result = await agent.run("Research recent developments in AI agent frameworks.")
+```
+
+#### Multi-Agent Setup with Subagents
+
+When building a multi-agent system, subagent configurations are registered with `AgentFactory`:
+
+```python
+from icogito.factory import AgentFactory
+from icogito.utils.load_agent_config import load_agent_config
+
+# Load root agent config and subagent configs
+sub_config = load_agent_config("configs/sub_researcher_config.yaml")
+root_config = load_agent_config("configs/root_manager_config.yaml")
+
+# Register subagent configs map
+subagent_configs = {
+    sub_config.agent_name: sub_config
+}
+
+factory = AgentFactory(
+    openrouter_api_key=os.getenv("OPENROUTER_API_KEY"),
+    subagent_configs=subagent_configs
+)
+
+# Build the root agent (automatically wires subagents recursively)
+root_agent = factory.create_agent(root_config)
+```
+
+---
+
+## Development & Testing
+
+To run the full test suite using `pytest`:
+
+```bash
+uv run --extra test pytest
+```
+
+---
+
+## Authors
+
+- **Daniel Rondon** — [hello@danielrondon.com](mailto:hello@danielrondon.com)

icogito-0.1.0/README.md

@@ -0,0 +1,172 @@
+# icogito
+
+> A modern Python CLI framework to build Agent/Multi-Agent systems on top of `pydantic-ai`, `pydantic-ai-harness`, OpenRouter, and Tavily tools.
+
+`icogito` provides an end-to-end toolkit for scaffolding, configuring, and running production-grade AI agent and multi-agent architectures. It integrates durable execution via Prefect, modular tool registry integration (including Tavily search, fetch, and crawl tools), and OpenRouter model routing.
+
+---
+
+## Key Features
+
+- **CLI-Driven Scaffolding**: Easily create standardized directory structures (`agents/`, `configs/`, `prompts/`, `schemas/`, `tools/`, `utils/`) using `icogito init`.
+- **Interactive Configuration**: Build single-agent and multi-agent workflow configurations interactively with `icogito configure`.
+- **System Diagnostics**: Verify tools, environment setup, and framework status with `icogito doctor`.
+- **Agent Factory**: Instantiates `pydantic-ai` Agents dynamically from YAML configurations (`AgentConfig`).
+- **Durable Execution & Subagents**: Supports task durability via `PrefectDurability` and hierarchical multi-agent delegation via `SubAgents`.
+- **Built-in Web Tools**: Tavily web integration for search, fetch, and crawl capabilities with built-in retry handling.
+
+---
+
+## Get Started
+
+### Prerequisites
+
+- **Python**: Version `>= 3.12`
+- **uv**: Recommended fast Python package and environment manager ([docs.astral.sh/uv](https://docs.astral.sh/uv/))
+- **API Keys**:
+  - `OPENROUTER_API_KEY`: Required for model inference via OpenRouter.
+  - `TAVILY_API_KEY`: Required when using Tavily web tools (`web_search`, `web_fetch`, `web_crawl`).
+
+### Installation
+
+Clone the repository and install dependencies using `uv`:
+
+```bash
+# Clone the repository
+git clone https://github.com/danielrondon/icogito.git
+cd icogito
+
+# Sync project dependencies into .venv
+uv sync
+
+# (Optional) Sync test extra dependencies if developing or running tests
+uv sync --extra test
+```
+
+### Local Environment Setup
+
+Configure your environment variables before running agent workflows or tools:
+
+```bash
+export OPENROUTER_API_KEY="your-openrouter-api-key"
+export TAVILY_API_KEY="your-tavily-api-key"
+```
+
+---
+
+## Usage
+
+### CLI Commands
+
+The `icogito` CLI provides commands for project initialization, diagnostics, and agent configuration.
+
+#### 1. Initialize Project Scaffolding (`icogito init`)
+
+Scaffold a standard agent directory structure in your project or a target directory:
+
+```bash
+# Initialize scaffolding in the current directory
+uv run icogito init
+
+# Or specify a target directory
+uv run icogito init ./my_agent_project
+```
+
+This creates the following directory layout:
+```
+.
+├── agents/
+├── configs/
+├── prompts/
+├── schemas/
+├── tools/
+└── utils/
+```
+
+#### 2. System Diagnostics (`icogito doctor`)
+
+Check system environment status, global app directory path, available Tavily web tools, and `AgentFactory` readiness:
+
+```bash
+# Run standard diagnostic check
+uv run icogito doctor
+
+# Verbose diagnostic output
+uv run icogito doctor --verbose
+```
+
+#### 3. Interactive Agent Configuration (`icogito configure`)
+
+Interactively configure single or multi-agent systems. This wizard prompts for agent names, OpenRouter models, providers, instructions, enabled tools, and subagents, then generates the corresponding YAML configs in `configs/` and Markdown instructions in `prompts/`:
+
+```bash
+uv run icogito configure
+```
+
+---
+
+### Programmatic Usage
+
+`icogito` provides high-level utilities and `AgentFactory` for loading configs and instantiating runtime agents.
+
+#### Loading Configuration and Instantiating Agents
+
+```python
+import os
+from icogito.factory import AgentFactory
+from icogito.utils.load_agent_config import load_agent_config
+
+# Load agent configuration from YAML
+config = load_agent_config("configs/research_agent_config.yaml")
+
+# Initialize AgentFactory with your OpenRouter API Key
+factory = AgentFactory(openrouter_api_key=os.getenv("OPENROUTER_API_KEY"))
+
+# Create a pydantic-ai Agent instance
+agent = factory.create_agent(config)
+
+# Run the agent (async)
+# result = await agent.run("Research recent developments in AI agent frameworks.")
+```
+
+#### Multi-Agent Setup with Subagents
+
+When building a multi-agent system, subagent configurations are registered with `AgentFactory`:
+
+```python
+from icogito.factory import AgentFactory
+from icogito.utils.load_agent_config import load_agent_config
+
+# Load root agent config and subagent configs
+sub_config = load_agent_config("configs/sub_researcher_config.yaml")
+root_config = load_agent_config("configs/root_manager_config.yaml")
+
+# Register subagent configs map
+subagent_configs = {
+    sub_config.agent_name: sub_config
+}
+
+factory = AgentFactory(
+    openrouter_api_key=os.getenv("OPENROUTER_API_KEY"),
+    subagent_configs=subagent_configs
+)
+
+# Build the root agent (automatically wires subagents recursively)
+root_agent = factory.create_agent(root_config)
+```
+
+---
+
+## Development & Testing
+
+To run the full test suite using `pytest`:
+
+```bash
+uv run --extra test pytest
+```
+
+---
+
+## Authors
+
+- **Daniel Rondon** — [hello@danielrondon.com](mailto:hello@danielrondon.com)

icogito-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[project]
+name = "icogito"
+version = "0.1.0"
+description = "A modern Python CLI framework to build Agent/Multi-Agents systems"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "graphifyy>=0.9.67",
+    "loguru>=0.7.3",
+    "pydantic>=2.13.5",
+    "pydantic-ai>=2.48.0",
+    "pydantic-ai-harness>=0.34.0",
+    "pyyaml>=6.0.3",
+    "questionary>=2.1.1",
+    "tavily-python>=0.8.4",
+    "typer>=0.27.2",
+]
+
+[[project.authors]]
+name = "Daniel Rondon"
+email = "hello@danielrondon.com"
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0.0",
+    "pytest-mock>=3.12.0",
+]
+
+[project.scripts]
+icogito = "icogito.cli:main"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.12"
+files = [
+    "src",
+    "tests",
+]
+warn_unused_ignores = true
+warn_return_any = true
+check_untyped_defs = true
+
+[[tool.mypy.overrides]]
+module = [
+    "tavily",
+    "tavily.*",
+]
+ignore_missing_imports = true
+
+[build-system]
+requires = ["uv_build>=0.12.14,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mypy>=2.4.0",
+    "pytest>=8.0.0",
+    "pytest-mock>=3.12.0",
+    "types-pyyaml>=6.0.12.20260906",
+    "types-requests>=2.33.0.20261006",
+]

icogito-0.1.0/pyproject.toml.orig

@@ -0,0 +1,57 @@
+[project]
+name = "icogito"
+version = "0.1.0"
+description = "A modern Python CLI framework to build Agent/Multi-Agents systems"
+readme = "README.md"
+authors = [
+    { name = "Daniel Rondon", email = "hello@danielrondon.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "graphifyy>=0.9.67",
+    "loguru>=0.7.3",
+    "pydantic>=2.13.5",
+    "pydantic-ai>=2.48.0",
+    "pydantic-ai-harness>=0.34.0",
+    "pyyaml>=6.0.3",
+    "questionary>=2.1.1",
+    "tavily-python>=0.8.4",
+    "typer>=0.27.2",
+]
+
+[project.optional-dependencies]
+test = [
+  "pytest>=8.0.0",
+  "pytest-mock>=3.12.0",
+]
+
+[project.scripts]
+icogito = "icogito.cli:main"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["uv_build>=0.12.14,<0.14.0"]
+build-backend = "uv_build"
+
+[tool.mypy]
+python_version = "3.12"
+files = ["src", "tests"]
+warn_unused_ignores = true
+warn_return_any = true
+check_untyped_defs = true
+
+[[tool.mypy.overrides]]
+module = ["tavily", "tavily.*"]
+ignore_missing_imports = true
+
+[dependency-groups]
+dev = [
+    "mypy>=2.4.0",
+    "pytest>=8.0.0",
+    "pytest-mock>=3.12.0",
+    "types-pyyaml>=6.0.12.20260906",
+    "types-requests>=2.33.0.20261006",
+]

icogito-0.1.0/src/icogito/__init__.py

@@ -0,0 +1,6 @@
+# src/icogito/__init__.py
+from .factory import AgentFactory
+from .models import AgentConfig
+from .core import create_scaffolding
+
+__all__ = ["AgentFactory", "AgentConfig", "create_scaffolding"]

icogito-0.1.0/src/icogito/cli.py

@@ -0,0 +1,168 @@
+from pathlib import Path
+from typing import Optional
+import typer
+import questionary
+
+from icogito import core
+from icogito.models import AgentConfig
+
+APP_NAME = "icogito"
+
+
+def get_global_app_dir() -> Path:
+    """Returns the global OS-appropriate application directory for icogito."""
+    app_dir = Path(typer.get_app_dir(APP_NAME))
+    app_dir.mkdir(parents=True, exist_ok=True)
+    return app_dir
+
+
+app = typer.Typer(
+    name="icogito-cli",
+    help="A modern Python CLI framework to build Agent/Multi-Agents systems.",
+    add_completion=True,
+)
+
+
+@app.command()
+def init(
+    target_dir: Path = typer.Argument(
+        default=Path.cwd(),
+        help="Target directory for the new project",
+    ),
+    force: bool = typer.Option(False, "--force", "-f", help="Force re-initialization"),
+):
+    """
+    Initialize directory scaffolding for a new agent project.
+    """
+    typer.secho(f"Initializing agent scaffolding at {target_dir}...", fg=typer.colors.GREEN)
+    core.create_scaffolding(target_dir)
+    typer.secho(
+        f"Successfully generated directory structure at {target_dir}.",
+        fg=typer.colors.GREEN,
+    )
+
+
+@app.command()
+def doctor(
+    verbose: Optional[bool] = typer.Option(False, "--verbose", "-v", help="Show extra details")
+):
+    """
+    Check the system status.
+    """
+    global_app_dir = get_global_app_dir()
+    status = core.get_doctor_status(verbose=bool(verbose))
+    typer.echo(f"System status: {status['status']}")
+    typer.echo(f"Global App Directory: {global_app_dir}")
+    typer.echo(f"Available Tavily tools: {', '.join(status['tools_available'])}")
+    typer.echo(f"AgentFactory ready: {status['agent_factory_ready']}")
+
+    if verbose and "details" in status:
+        typer.echo(f"Detailed logs: {status['details']}")
+
+
+def prompt_agent_config(agent: str, is_sub_agent: bool = False) -> AgentConfig:
+    """Interactively prompts user for agent configuration via questionary."""
+    agent_name = questionary.text(
+        f"Enter agent name for {agent}:",
+        default="research_agent"
+    ).ask()
+    model_name = questionary.select(
+        "Select OpenRouter model:",
+        choices=[
+            "openai/gpt-4o-mini",
+            "openai/gpt-6-luna",
+            "openai/gpt-6-luna-pro"
+        ]
+    ).ask()
+    model_providers = questionary.checkbox(
+        "Select OpenRouter Providers:",
+        choices=[
+            "openai",
+            "openai/flex",
+            "azure"
+        ]
+    ).ask()
+    allow_fallbacks = questionary.confirm(
+        "Allow model provider fallbacks?",
+        default=False
+    ).ask()
+    agent_instruction = questionary.text(
+        "Enter agent's instructions:",
+        default="You are an AI agent built with icogito"
+    ).ask()
+    selected_tools = questionary.checkbox(
+        "Select tools to enable for the agent:",
+        choices=[
+            "web_search",
+            "web_fetch",
+            "web_crawl"
+        ],
+        default="web_search"
+    ).ask()
+
+    if is_sub_agent:
+        number_of_sub_agents = 0
+    else:
+        number_of_sub_agents = int(
+            questionary.text(
+                "Number of sub agents: ",
+                validate=lambda text: text.isdigit() or "Please enter a valid number"
+            ).ask()
+        )
+
+    sub_agents_names = []
+    if number_of_sub_agents > 0:
+        for i in range(int(number_of_sub_agents)):
+            subagent_config = prompt_agent_config(f"{agent_name}'s sub-agent-{i}", is_sub_agent=True)
+            sub_agents_names.append(subagent_config.agent_name)
+            core.save_config(subagent_config)
+
+    config = core.create_agent_config(
+        agent_name=agent_name,
+        model_name=model_name,
+        model_providers=model_providers,
+        allow_fallbacks=allow_fallbacks,
+        agent_instruction=agent_instruction,
+        selected_tools=selected_tools,
+        sub_agents_names=sub_agents_names,
+    )
+    return config
+
+
+@app.command()
+def configure():
+    """
+    Interactively configure agent workflows with questionary prompts.
+    """
+    typer.echo("--- Dynamic Agent Configuration ---")
+    enable_multi_agent = questionary.select(
+        "Enable multi-agent configuration?",
+        choices=[
+            "Yes",
+            "No"
+        ],
+    ).ask()
+
+    if enable_multi_agent == "No":
+        config = prompt_agent_config("root-agent")
+        core.save_config(config)
+    else:
+        number_of_agents = int(
+            questionary.text(
+                "Number of root agents: ",
+                validate=lambda text: text.isdigit() or "Please enter a valid number"
+            ).ask()
+        )
+        for i in range(int(number_of_agents)):
+            config = prompt_agent_config(f"root-agent-{i}")
+            core.save_config(config)
+
+    typer.echo("AgentConfig initialized successfully!")
+
+
+def main():
+    app()
+
+
+if __name__ == "__main__":
+    main()

icogito-0.1.0/src/icogito/core.py

@@ -0,0 +1,81 @@
+from pathlib import Path
+from typing import Optional, List, Dict, Any
+
+from icogito.factory import AgentFactory
+from icogito.tools.tavily_web_tools import web_search, web_fetch, web_crawl
+from icogito.models import AgentConfig
+from icogito.utils.save_agent_config import save_agent_config
+from icogito.utils.save_prompt_instruction import save_prompt_instruction
+
+
+def create_scaffolding(target_dir: Path) -> List[Path]:
+    """Creates directory structure for agent scaffolding."""
+    subdirs = ["agents", "configs", "schemas", "prompts", "tools", "utils"]
+
+    target_dir.mkdir(parents=True, exist_ok=True)
+    created_paths = [target_dir]
+
+    for subdir in subdirs:
+        dir_path = target_dir / subdir
+        dir_path.mkdir(parents=True, exist_ok=True)
+        created_paths.append(dir_path)
+
+    return created_paths
+
+
+def get_doctor_status(verbose: bool = False) -> Dict[str, Any]:
+    """Retrieves system status and availability of tools and components."""
+    tools_available = [web_search.__name__, web_fetch.__name__, web_crawl.__name__]
+    status: Dict[str, Any] = {
+        "status": "OK",
+        "tools_available": tools_available,
+        "agent_factory_ready": AgentFactory.__name__,
+    }
+    if verbose:
+        status["details"] = "All services reporting nominal operations."
+    return status
+
+
+def create_agent_config(
+    agent_name: str,
+    model_name: str,
+    model_providers: List[str],
+    allow_fallbacks: bool,
+    agent_instruction: str,
+    selected_tools: List[str],
+    sub_agents_names: Optional[List[str]] = None,
+    prompts_dir: Path | str = "prompts",
+    configs_dir: Path | str = "configs",
+) -> AgentConfig:
+    """Constructs an AgentConfig object with target prompt and config paths."""
+    target_prompts_dir = Path(prompts_dir)
+    target_config_dir = Path(configs_dir)
+    target_prompts_dir.mkdir(parents=True, exist_ok=True)
+    target_config_dir.mkdir(parents=True, exist_ok=True)
+
+    instructions_path = f"{target_prompts_dir}/{agent_name}_instruction.md"
+    config_path = f"{target_config_dir}/{agent_name}_agent.yaml"
+
+    return AgentConfig(
+        model_name=model_name,
+        agent_name=agent_name,
+        agent_instruction=agent_instruction,
+        instructions_path=instructions_path,
+        config_file_path=config_path,
+        settings_openrouter_provider_list=model_providers,
+        allow_fallbacks=allow_fallbacks,
+        subagents_list=sub_agents_names or [],
+        tools_list=selected_tools,
+    )
+
+
+def save_config(config: AgentConfig) -> None:
+    """Saves the agent configuration file and prompt instruction."""
+    save_agent_config(
+        config_file=config.config_file_path,
+        config_data=config
+    )
+    save_prompt_instruction(
+        path=config.instructions_path,
+        instruction_data=config.agent_instruction
+    )

icogito-0.1.0/src/icogito/factory.py

@@ -0,0 +1,144 @@
+from pydantic_ai import Agent
+from pydantic_ai_harness import SubAgent, SubAgents, ToolOutputLimits
+from pydantic_ai.toolsets.abstract import AbstractToolset
+# from pydantic_ai.durable_exec.prefect import PrefectDurability, TaskConfig
+from pydantic_ai.models.openrouter import OpenRouterModel, OpenRouterModelSettings
+from pydantic_ai.providers.openrouter import OpenRouterProvider
+from pydantic_ai.output import ToolOutput
+from pydantic_ai.toolsets.function import FunctionToolset
+from icogito.utils.get_prompt_instruction import get_prompt_instruction
+from icogito.tools.tavily_web_tools import web_fetch, web_search
+from icogito.models import AgentConfig
+from typing import Callable, Any
+from loguru import logger
+
+class IdentifiedToolOutputLimits(ToolOutputLimits):
+    """ToolOutputLimits, but stamps `id` onto its internal `read_tool_result` toolset.
+
+    Upstream bug: `ToolOutputLimits.get_toolset()` always returns a bare
+    `FunctionToolset([read_tool_result])` with no id, ignoring `self.id`.
+    A leaf toolset without an id breaks Prefect/Temporal durable execution.
+    """
+
+    def get_toolset(self) -> AbstractToolset[Any] | Callable[..., Any] | None:
+        toolset = super().get_toolset()
+        if isinstance(toolset, AbstractToolset) and toolset.id is None:
+            toolset._id = self.id  # type: ignore[attr-defined]
+        return toolset
+
+
+class IdentifiedSubAgents(SubAgents):
+    """SubAgents, but stamps `id` onto its internal `delegate_task` toolset.
+
+    Same upstream bug as `ToolOutputLimits`: `SubAgents.get_toolset()` never
+    forwards `self.id` to the `SubAgentToolset` it builds.
+    """
+
+    def get_toolset(self) -> AbstractToolset[Any] | Callable[..., Any] | None:
+        toolset = super().get_toolset()
+        if isinstance(toolset, AbstractToolset) and toolset.id is None:
+            toolset._id = self.id  # type: ignore[attr-defined]
+        return toolset
+
+
+class AgentFactory:
+    def __init__(self, openrouter_api_key: str | None, subagent_configs: dict[str, AgentConfig] | None = None):
+        self.openrouter_api_key: str | None = openrouter_api_key
+        # Provide a lookup map for subagent configs so we can recursively build them
+        self.subagent_configs: dict[str, AgentConfig] = subagent_configs or {}
+        
+        # Tool registry mapping config strings to actual Python functions
+        self.tool_registry: dict[str, Callable] = {
+            "web_fetch": web_fetch,
+            "web_search": web_search,
+        }
+
+    def create_subagent(self, config: AgentConfig) -> SubAgent:
+        return SubAgent(self.create_agent(config=config))
+    
+    def create_agent(self, config: AgentConfig) -> Agent:
+        settings = OpenRouterModelSettings(
+            openrouter_cache_instructions=True,
+            openrouter_provider={
+                "order": config.settings_openrouter_provider_list, # TODO: Add to accept None as value
+                "allow_fallbacks": False
+            }
+        )
+        model = OpenRouterModel(
+            config.model_name,
+            provider=OpenRouterProvider(api_key=self.openrouter_api_key),
+        )
+
+        # 3. Build base kwargs for the Agent
+        agent_kwargs = {
+            "model": model,
+            "name": config.agent_name,
+            "model_settings": settings,
+            "instructions": get_prompt_instruction(config.instructions_path),
+            "description": get_prompt_instruction(config.sub_descriptions_path),
+            "retries": {'output': config.retries_output},
+            "max_concurrency": config.max_concurrency,
+        }
+
+        # 4. Conditionally add Output Type and Dependencies Type
+        if config.output_schema:
+            agent_kwargs["output_type"] = ToolOutput(config.output_schema)
+        if config.deps_type:
+            agent_kwargs["deps_type"] = config.deps_type
+
+        # 5. Conditionally add Capabilities (Subagents)
+        capabilities: list[Any] = [
+            IdentifiedToolOutputLimits(id=f"{config.agent_name}_tool_output_limits"),
+            # PrefectDurability(
+            #     model_task_config=TaskConfig(
+            #         retries=3,
+            #         retry_delay_seconds=[1.0, 2.0, 5.0],  # Exponential backoff
+            #         timeout_seconds=600.0,
+            #         log_prints=True
+            #     )
+            # ),
+        ]
+        if config.subagents_list:
+            subagents_pool = self._get_subagents_pool(config.subagents_list)
+            if subagents_pool:
+                capabilities.append(
+                    IdentifiedSubAgents(
+                        agents=subagents_pool,
+                        agent_folders=None,
+                        tool_retries=3,
+                        id=f"{config.agent_name}_subagents",
+                    )
+                )
+        agent_kwargs["capabilities"] = capabilities
+
+        # 6. Conditionally add Tools
+        if config.tools_list:
+            agent_kwargs["toolsets"] = [
+                FunctionToolset(self._get_tools_pool(config.tools_list), id=f"{config.agent_name}_tools")
+            ]
+
+        # 7. Unpack kwargs into the Agent
+        return Agent(**agent_kwargs) # type: ignore[call-overload, no-any-return]
+
+    def _get_tools_pool(self, tools_list: list[str]) -> list[Callable]:
+        """Maps list of string names to actual tool functions."""
+        tool_seq = []
+        for tool_name in tools_list:
+            tool_fn = self.tool_registry.get(tool_name)
+            if tool_fn:
+                tool_seq.append(tool_fn)
+            else:
+                logger.warning(f"Tool '{tool_name}' not found in registry.")
+        return tool_seq
+
+    def _get_subagents_pool(self, subagents_list: list[str]) -> list[SubAgent]:
+        """Maps list of string names to actual SubAgent instances recursively."""
+        subagent_seq = []
+        for subagent_name in subagents_list:
+            sub_config = self.subagent_configs.get(subagent_name)
+            if sub_config:
+                # Recursively create the subagent using the mapped config
+                subagent_seq.append(self.create_subagent(sub_config))
+            else:
+                logger.warning(f"Subagent config for '{subagent_name}' not found in registry.")
+        return subagent_seq

icogito-0.1.0/src/icogito/models.py

@@ -0,0 +1,58 @@
+from pydantic import BaseModel, Field
+from typing import Optional
+from datetime import datetime, timezone
+from typing import Type, Any
+from dataclasses import dataclass, field
+
+@dataclass
+class ResearchState:
+    visited_urls: set[str] = field(default_factory=set)
+    searched_queries: set[str] = field(default_factory=set)
+
+class AgentConfig(BaseModel):
+    model_name: str
+    agent_name: str
+    instructions_path: str
+    config_file_path: str
+    agent_instruction: str
+    allow_fallbacks: bool
+    settings_openrouter_provider_list: list[str] # TODO: Add to accept None as value
+    sub_instructions_path: str | None = None
+    sub_descriptions_path: str | None = None
+    sub_agent_description: str | None = None
+    subagents_list: list[str] | None = None
+    tools_list: list[str] | None = None
+    output_schema: Type[BaseModel] | None = None
+    deps_type: Type[Any] | None = None
+    retries_output: int = 3
+    max_concurrency: int = 1
+
+class UsageLimitErrorResponse(BaseModel):
+    error_code: str = Field(
+        default="UsageLimitExceeded",
+        description="The standard error code identifier for routing."
+    )
+    message: str = Field(
+        ...,
+        description="The raw error message explaining the usage limit violation."
+    )
+    limit_type: Optional[str] = Field(
+        default=None,
+        description="The type of quota exceeded (e.g., 'requests_per_minute', 'tokens_per_day', 'budget')."
+    )
+    current_usage: Optional[int | float] = Field(
+        default=None,
+        description="The recorded usage at the time the exception was raised."
+    )
+    max_limit: Optional[int | float] = Field(
+        default=None,
+        description="The maximum allowed threshold for the specified limit_type."
+    )
+    retry_after_seconds: Optional[int] = Field(
+        default=None,
+        description="The suggested backoff time in seconds extracted from the API response headers."
+    )
+    timestamp: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="The exact UTC timestamp when the error occurred."
+    )

icogito-0.1.0/src/icogito/tools/tavily_web_tools.py

@@ -0,0 +1,72 @@
+from tavily import AsyncTavilyClient
+from pydantic_ai import ModelRetry, RunContext
+from icogito.models import ResearchState
+from dotenv import load_dotenv
+from loguru import logger
+from typing import Any, Literal, cast
+import os
+
+load_dotenv()
+
+
+def get_tavily_client() -> AsyncTavilyClient:
+    api_key = os.getenv("TAVILY_API_KEY")
+    if not api_key:
+        logger.error("TAVILY_API_KEY is missing!")
+        raise ValueError("TAVILY_API_KEY is missing! Check your .env file.")
+    return AsyncTavilyClient(api_key=api_key)
+
+
+BLOCKED_MESSAGE = (
+    "This URL is blocked by a paywall or anti-bot system. DO NOT retry "
+    "fetching this URL. Proceed with the draft using only the available "
+    "search context."
+)
+
+async def web_search(
+        search: str,
+        topic: Literal['general', 'news', 'finance'] = "news",
+        days: int = 7
+) -> dict:
+    """Performs a web search specifically for recent news using Tavily"""
+    logger.info(f"Web search looking for {search}")
+    tavily_client = get_tavily_client()
+    search_response = await tavily_client.search(
+        query=search,
+        topic=topic,
+        days=days,
+        max_results=20
+    )
+    if search_response is None:
+        logger.warning("Tavily found nothing or got blocked")
+        raise ModelRetry(BLOCKED_MESSAGE)
+    return cast(dict[str, Any], search_response)
+
+async def web_fetch(ctx: RunContext[ResearchState], urls: str | list[str]) -> dict[str, Any]:
+    """Performs a web fetch using Tavily"""
+    for url in urls:
+        if url in ctx.deps.visited_urls:
+            return {"error": "URL already processed. Stop fetching this URL and synthesize."}
+        ctx.deps.visited_urls.add(url)
+    logger.info(f"Extracting from {urls}")
+    tavily_client = get_tavily_client()
+    response = await tavily_client.extract(
+        urls=urls,
+        extract_depth="advanced",
+        format="markdown"
+    )
+    if not response or "cloudflare" in str(response).lower():
+        logger.warning("Tavily found nothing or got blocked")
+        raise ModelRetry(BLOCKED_MESSAGE)
+    return cast(dict[str, Any], response)
+
+
+async def web_crawl(url: str, instructions: str) -> dict[str, Any]:
+    """Performs a smart web crawling using Tavily"""
+    logger.info(f"Crawling: {url}")
+    tavily_client = get_tavily_client()
+    response = await tavily_client.crawl(url, instructions=instructions)
+    if not response:
+        logger.warning("Tavily found nothing or got blocked")
+        raise ModelRetry(BLOCKED_MESSAGE)
+    return cast(dict[str, Any], response)

icogito-0.1.0/src/icogito/utils/get_prompt_instruction.py

@@ -0,0 +1,18 @@
+from pathlib import Path
+from typing import Optional
+
+# Get the project root directory (utils/ -> project_root)
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+
+def get_prompt_instruction(path: Optional[str | Path]) -> Optional[str]:
+    # If the YAML didn't provide a path (it's None or empty string), return None safely
+    if not path:
+        return None
+        
+    file_path = Path(path)
+    
+    # If a relative path was passed, resolve it against the project root
+    if not file_path.is_absolute():
+        file_path = PROJECT_ROOT / file_path
+        
+    return file_path.read_text(encoding="utf-8")

icogito-0.1.0/src/icogito/utils/load_agent_config.py

@@ -0,0 +1,9 @@
+import yaml
+from icogito.models import AgentConfig
+
+def load_agent_config(yaml_path: str) -> AgentConfig:
+    """Loads a single YAML file and converts it into an AgentConfig model."""
+    with open(yaml_path, 'r') as file:
+        raw_config = yaml.safe_load(file)
+        
+    return AgentConfig(**raw_config)

icogito-0.1.0/src/icogito/utils/save_agent_config.py

@@ -0,0 +1,20 @@
+import yaml
+from typing import Optional
+from pathlib import Path
+from icogito.models import AgentConfig
+
+def save_agent_config(config_file: Optional[str | Path], config_data: AgentConfig) -> Optional[str | Path] | None:
+    """Saves a single YAML file and converts it into an AgentConfig model."""
+    # If the file didn't provide a path (it's None or empty string), return None safely
+    if not config_file:
+        return None
+    file_path = Path(config_file)
+    # If a relative path was passed, resolve it against the current working directory
+    if not file_path.is_absolute():
+        file_path = Path.cwd() / file_path
+    try:
+        with open(file_path, "w") as file:
+            yaml.dump(config_data.model_dump(), file, sort_keys=False)
+        return file_path
+    except FileNotFoundError as e:
+        raise e

icogito-0.1.0/src/icogito/utils/save_prompt_instruction.py

@@ -0,0 +1,18 @@
+from pathlib import Path
+from typing import Optional
+
+def save_prompt_instruction(path: Optional[str | Path], instruction_data: str) -> Optional[str | Path] | None:
+    """Saves agent's instruction into a markdown file."""
+    # If the file didn't provide a path (it's None or empty string), return None safely
+    if not path:
+        return None
+    file_path = Path(path)
+    # If a relative path was passed, resolve it against the current working directory
+    if not file_path.is_absolute():
+        file_path = Path.cwd() / file_path
+    try:
+        with open(file_path, 'w') as file:
+            file.write(instruction_data)
+        return file_path
+    except FileNotFoundError as e:
+        raise e