agentloom 0.1.0__py3-none-any.whl

agentloom/__init__.py

@@ -0,0 +1,3 @@
+"""AgentLoom: Production-ready agentic workflow orchestrator."""
+
+__version__ = "0.1.0"

agentloom/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI entry point for AgentLoom."""

agentloom/cli/info.py

@@ -0,0 +1,66 @@
+"""CLI command: show system information."""
+
+from __future__ import annotations
+
+import os
+import platform
+import sys
+
+import typer
+
+from agentloom import __version__
+from agentloom.compat import is_available, try_import
+
+
+def info() -> None:
+    """Show AgentLoom version, dependencies, and system information."""
+    typer.echo(f"AgentLoom v{__version__}")
+    typer.echo(f"{'=' * 40}")
+
+    # Python info
+    typer.echo(f"\nPython:    {sys.version.split()[0]}")
+    typer.echo(f"Platform:  {platform.platform()}")
+    typer.echo(f"Arch:      {platform.machine()}")
+
+    # Core dependencies
+    typer.echo("\nCore dependencies:")
+    for pkg in ["pydantic", "httpx", "pyyaml", "typer", "anyio"]:
+        _show_dep(pkg)
+
+    # Optional dependencies
+    typer.echo("\nOptional (observability):")
+    otel = try_import("opentelemetry.sdk", extra="observability")
+    prom = try_import("prometheus_client", extra="observability")
+    typer.echo(f"  opentelemetry: {'installed' if is_available(otel) else 'not installed'}")
+    typer.echo(f"  prometheus:    {'installed' if is_available(prom) else 'not installed'}")
+
+    # Provider API keys
+    typer.echo("\nProviders:")
+    providers = {
+        "OpenAI": "OPENAI_API_KEY",
+        "Anthropic": "ANTHROPIC_API_KEY",
+        "Google": "GOOGLE_API_KEY",
+        "Ollama": "OLLAMA_BASE_URL",
+    }
+    for name, env_var in providers.items():
+        value = os.environ.get(env_var, "")
+        if env_var == "OLLAMA_BASE_URL":
+            status = value or "http://localhost:11434 (default)"
+        elif value:
+            status = f"configured ({value[:8]}...)"
+        else:
+            status = "not configured"
+        typer.echo(f"  {name:12s} {status}")
+
+    typer.echo("")
+
+
+def _show_dep(package: str) -> None:
+    """Show version of an installed package."""
+    try:
+        from importlib.metadata import version
+
+        ver = version(package.replace("-", "_"))
+        typer.echo(f"  {package:12s} {ver}")
+    except Exception:
+        typer.echo(f"  {package:12s} not found")

agentloom/cli/main.py

@@ -0,0 +1,25 @@
+"""Main CLI application for AgentLoom."""
+
+from __future__ import annotations
+
+import typer
+
+app = typer.Typer(
+    name="agentloom",
+    help="AgentLoom: Production-ready agentic workflow orchestrator.",
+    no_args_is_help=True,
+)
+
+from agentloom.cli.info import info  # noqa: E402
+from agentloom.cli.run import run  # noqa: E402
+from agentloom.cli.validate import validate  # noqa: E402
+from agentloom.cli.visualize import visualize  # noqa: E402
+
+app.command("run")(run)
+app.command("validate")(validate)
+app.command("visualize")(visualize)
+app.command("info")(info)
+
+
+if __name__ == "__main__":
+    app()

agentloom/cli/run.py

@@ -0,0 +1,236 @@
+"""CLI command: run a workflow."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import anyio
+import typer
+
+from agentloom.core.parser import WorkflowParser
+from agentloom.core.results import WorkflowStatus
+from agentloom.core.state import StateManager
+
+if TYPE_CHECKING:
+    from agentloom.observability.observer import WorkflowObserver
+    from agentloom.providers.gateway import ProviderGateway
+
+
+def run(
+    workflow_path: Path = typer.Argument(..., help="Path to the workflow YAML file.", exists=True),
+    state: list[str] = typer.Option(
+        [], "--state", "-s", help="State variables as key=value pairs."
+    ),
+    provider: str | None = typer.Option(
+        None, "--provider", "-p", help="Override default provider."
+    ),
+    model: str | None = typer.Option(None, "--model", "-m", help="Override default model."),
+    budget: float | None = typer.Option(None, "--budget", "-b", help="Maximum budget in USD."),
+    lite: bool = typer.Option(False, "--lite", help="Run in lite mode (no observability)."),
+    output_json: bool = typer.Option(False, "--json", help="Output results as JSON."),
+) -> None:
+    """Execute a workflow from a YAML definition file."""
+    anyio.run(_run_async, workflow_path, state, provider, model, budget, lite, output_json)
+
+
+async def _run_async(
+    workflow_path: Path,
+    state_args: list[str],
+    provider_override: str | None,
+    model_override: str | None,
+    budget: float | None,
+    lite: bool,
+    output_json: bool,
+) -> None:
+    """Async implementation of the run command."""
+    from agentloom.core.engine import WorkflowEngine
+    from agentloom.providers.gateway import ProviderGateway
+    from agentloom.tools.builtins import register_builtins
+    from agentloom.tools.registry import ToolRegistry
+
+    # Parse workflow
+    try:
+        workflow = WorkflowParser.from_yaml(workflow_path)
+    except Exception as e:
+        typer.echo(f"Error loading workflow: {e}", err=True)
+        raise typer.Exit(1)
+
+    # Apply overrides
+    if provider_override:
+        workflow.config.provider = provider_override
+    if model_override:
+        workflow.config.model = model_override
+    if budget is not None:
+        workflow.config.budget_usd = budget
+
+    # Parse state overrides
+    initial_state = dict(workflow.state)
+    for item in state_args:
+        if "=" not in item:
+            typer.echo(f"Invalid state format '{item}'. Use key=value.", err=True)
+            raise typer.Exit(1)
+        key, value = item.split("=", 1)
+        initial_state[key] = value
+
+    state_manager = StateManager(initial_state=initial_state)
+
+    # Setup provider gateway
+    gateway = ProviderGateway()
+    _setup_providers(gateway, workflow.config.provider)
+
+    # Setup tools
+    tool_registry = ToolRegistry()
+    register_builtins(tool_registry)
+
+    # Setup observability (unless --lite)
+    observer = _setup_observer(lite)
+
+    # Run engine
+    engine = WorkflowEngine(
+        workflow=workflow,
+        state_manager=state_manager,
+        provider_gateway=gateway,
+        tool_registry=tool_registry,
+        observer=observer,
+    )
+
+    typer.echo(f"Running workflow: {workflow.name}")
+    result = await engine.run()
+
+    # Output results
+    if output_json:
+        typer.echo(result.model_dump_json(indent=2))
+    else:
+        _print_result(result)
+
+    if observer:
+        observer.shutdown()
+    await gateway.close()
+
+    if result.status != WorkflowStatus.SUCCESS:
+        raise typer.Exit(1)
+
+
+def _setup_observer(lite: bool) -> WorkflowObserver | None:
+    """Create the observability observer unless running in lite mode."""
+    if lite:
+        return None
+
+    from agentloom.compat import is_available, try_import
+    from agentloom.observability.observer import WorkflowObserver
+
+    tracing_mod = try_import("opentelemetry.trace", extra="observability")
+    metrics_mod = try_import("opentelemetry.sdk.metrics", extra="observability")
+
+    tracing = None
+    metrics = None
+
+    if is_available(tracing_mod):
+        from agentloom.observability.tracing import TracingManager
+
+        tracing = TracingManager()
+
+    if is_available(metrics_mod):
+        from agentloom.observability.metrics import MetricsManager
+
+        metrics = MetricsManager()
+
+    if tracing or metrics:
+        return WorkflowObserver(tracing=tracing, metrics=metrics)
+
+    return None
+
+
+def _setup_providers(gateway: ProviderGateway, default_provider: str) -> None:
+    """Setup providers based on available API keys."""
+    # HACK: provider discovery from env vars — should really be in a config file
+    import os
+
+    if os.environ.get("OPENAI_API_KEY"):
+        from agentloom.providers.openai import OpenAIProvider
+
+        gateway.register(
+            OpenAIProvider(),
+            priority=0 if default_provider == "openai" else 10,
+            models=[
+                "gpt-4o-mini",
+                "gpt-4o",
+                "gpt-4.1",
+                "o4-mini",
+            ],
+        )
+
+    if os.environ.get("ANTHROPIC_API_KEY"):
+        from agentloom.providers.anthropic import AnthropicProvider
+
+        gateway.register(
+            AnthropicProvider(),
+            priority=0 if default_provider == "anthropic" else 10,
+            models=[
+                "claude-haiku-4-5-20251001",
+            ],
+        )
+
+    if os.environ.get("GOOGLE_API_KEY"):
+        from agentloom.providers.google import GoogleProvider
+
+        gateway.register(
+            GoogleProvider(),
+            priority=0 if default_provider == "google" else 10,
+            models=[
+                "gemini-2.0-flash",
+                "gemini-2.5-flash",
+            ],
+        )
+
+    # Ollama is always available as fallback (local/LAN)
+    from agentloom.providers.ollama import OllamaProvider
+
+    ollama_url = os.environ.get("OLLAMA_BASE_URL", "http://localhost:11434")
+    gateway.register(
+        OllamaProvider(base_url=ollama_url),
+        priority=0 if default_provider == "ollama" else 100,
+        is_fallback=True,
+    )
+
+
+def _print_result(result: object) -> None:
+    """Pretty-print a workflow result."""
+    from agentloom.core.results import StepStatus, WorkflowResult
+
+    r: WorkflowResult = result  # type: ignore[assignment]
+
+    status_icon = {
+        "success": "[OK]",
+        "failed": "[FAIL]",
+        "timeout": "[TIMEOUT]",
+        "budget_exceeded": "[BUDGET]",
+    }
+
+    typer.echo(f"\n{'=' * 60}")
+    typer.echo(f"Workflow: {r.workflow_name}")
+    typer.echo(f"Status:   {status_icon.get(r.status.value, '?')} {r.status.value}")
+    typer.echo(f"Duration: {r.total_duration_ms:.1f}ms")
+    typer.echo(f"Tokens:   {r.total_tokens}")
+    typer.echo(f"Cost:     ${r.total_cost_usd:.4f}")
+
+    if r.error:
+        typer.echo(f"Error:    {r.error}")
+
+    typer.echo("\nSteps:")
+    for step_id, sr in r.step_results.items():
+        icon = (
+            "[OK]"
+            if sr.status == StepStatus.SUCCESS
+            else ("[SKIP]" if sr.status == StepStatus.SKIPPED else "[FAIL]")
+        )
+        line = f"  {icon} {step_id} ({sr.duration_ms:.0f}ms)"
+        if sr.cost_usd > 0:
+            line += f" ${sr.cost_usd:.4f}"
+        typer.echo(line)
+
+    # Show final output
+    final_state = r.final_state
+    typer.echo(f"\nFinal State Keys: {list(final_state.keys())}")
+    typer.echo(f"{'=' * 60}")

agentloom/cli/validate.py

@@ -0,0 +1,48 @@
+"""CLI command: validate a workflow definition."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from agentloom.core.parser import WorkflowParser
+from agentloom.exceptions import ValidationError
+
+
+def validate(
+    workflow_path: Path = typer.Argument(..., help="Path to the workflow YAML file.", exists=True),
+) -> None:
+    """Validate a workflow YAML file for correctness."""
+    try:
+        workflow = WorkflowParser.from_yaml(workflow_path)
+    except ValidationError as e:
+        typer.echo(f"Validation FAILED:\n{e}", err=True)
+        raise typer.Exit(1)
+    except Exception as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
+
+    # Also validate the DAG
+    try:
+        dag = WorkflowParser.build_dag(workflow)
+    except ValidationError as e:
+        typer.echo(f"DAG validation FAILED:\n{e}", err=True)
+        raise typer.Exit(1)
+
+    layers = dag.execution_layers()
+
+    typer.echo(f"Workflow '{workflow.name}' is valid.")
+    typer.echo(f"  Version:  {workflow.version}")
+    typer.echo(f"  Steps:    {len(workflow.steps)}")
+    typer.echo(f"  Layers:   {len(layers)}")
+    typer.echo(f"  Provider: {workflow.config.provider}")
+    typer.echo(f"  Model:    {workflow.config.model}")
+
+    if workflow.config.budget_usd:
+        typer.echo(f"  Budget:   ${workflow.config.budget_usd:.2f}")
+
+    typer.echo("\n  Execution plan:")
+    for i, layer in enumerate(layers):
+        parallel = " (parallel)" if len(layer) > 1 else ""
+        typer.echo(f"    Layer {i}: {', '.join(layer)}{parallel}")

agentloom/cli/visualize.py

@@ -0,0 +1,118 @@
+"""CLI command: visualize a workflow DAG."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from agentloom.core.models import StepType
+from agentloom.core.parser import WorkflowParser
+from agentloom.exceptions import ValidationError
+
+
+def visualize(
+    workflow_path: Path = typer.Argument(..., help="Path to the workflow YAML file.", exists=True),
+    format: str = typer.Option("ascii", "--format", "-f", help="Output format: ascii or mermaid."),
+) -> None:
+    """Visualize a workflow as an ASCII diagram or Mermaid graph."""
+    try:
+        workflow = WorkflowParser.from_yaml(workflow_path)
+        dag = WorkflowParser.build_dag(workflow)
+    except (ValidationError, Exception) as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
+
+    if format == "mermaid":
+        _print_mermaid(workflow, dag)
+    else:
+        _print_ascii(workflow, dag)
+
+
+def _print_ascii(workflow: object, dag: object) -> None:
+    """Print an ASCII representation of the workflow DAG."""
+    from agentloom.core.dag import DAG
+    from agentloom.core.models import WorkflowDefinition
+
+    w: WorkflowDefinition = workflow  # type: ignore[assignment]
+    d: DAG = dag  # type: ignore[assignment]
+    layers = d.execution_layers()
+
+    step_types = {s.id: s.type for s in w.steps}
+    type_icons = {
+        StepType.LLM_CALL: "LLM",
+        StepType.TOOL: "TOOL",
+        StepType.ROUTER: "IF/ELSE",
+        StepType.SUBWORKFLOW: "SUB",
+    }
+
+    typer.echo(f"\n  Workflow: {w.name}")
+    typer.echo(f"  {'=' * 50}")
+
+    for i, layer in enumerate(layers):
+        if i > 0:
+            # Draw arrows from previous layer
+            typer.echo(f"  {'  |':^50}")
+            typer.echo(f"  {'  v':^50}")
+
+        # Draw steps in this layer
+        boxes = []
+        for step_id in layer:
+            stype = step_types.get(step_id, StepType.LLM_CALL)
+            icon = type_icons.get(stype, "?")
+            box = f"[{icon}: {step_id}]"
+            boxes.append(box)
+
+        if len(boxes) == 1:
+            typer.echo(f"  {boxes[0]:^50}")
+        else:
+            # Parallel steps side by side
+            line = "  " + "   ".join(boxes)
+            typer.echo(line)
+
+    typer.echo(f"  {'=' * 50}\n")
+
+
+def _print_mermaid(workflow: object, dag: object) -> None:
+    """Print a Mermaid graph definition."""
+    from agentloom.core.models import WorkflowDefinition
+
+    w: WorkflowDefinition = workflow  # type: ignore[assignment]
+
+    step_types = {s.id: s.type for s in w.steps}
+
+    typer.echo("```mermaid")
+    typer.echo("graph TD")
+
+    # Define nodes
+    for step in w.steps:
+        stype = step_types.get(step.id, StepType.LLM_CALL)
+        if stype == StepType.ROUTER:
+            typer.echo(f"    {step.id}{{{step.id}}}")
+        elif stype == StepType.TOOL:
+            typer.echo(f"    {step.id}[/{step.id}/]")
+        elif stype == StepType.SUBWORKFLOW:
+            typer.echo(f"    {step.id}[[{step.id}]]")
+        else:
+            typer.echo(f"    {step.id}[{step.id}]")
+
+    # Define edges
+    for step in w.steps:
+        for dep in step.depends_on:
+            dep_step = w.get_step(dep)
+            if dep_step and dep_step.type == StepType.ROUTER:
+                # Show router conditions as edge labels
+                for cond in dep_step.conditions:
+                    if cond.target == step.id:
+                        label = cond.expression[:20]
+                        typer.echo(f"    {dep} -->|{label}| {step.id}")
+                        break
+                else:
+                    if dep_step.default == step.id:
+                        typer.echo(f"    {dep} -->|default| {step.id}")
+                    else:
+                        typer.echo(f"    {dep} --> {step.id}")
+            else:
+                typer.echo(f"    {dep} --> {step.id}")
+
+    typer.echo("```")

agentloom/compat.py

@@ -0,0 +1,57 @@
+"""Conditional import mechanism for optional dependencies.
+
+Provides `try_import()` which returns the real module if available,
+or a MissingDependencyProxy that raises ImportError with install
+instructions on any attribute access.
+"""
+
+from __future__ import annotations
+
+import importlib
+from types import ModuleType
+
+
+class MissingDependencyProxy:
+    """Proxy object that raises ImportError with install instructions on attribute access."""
+
+    def __init__(self, module_name: str, extra: str = "all") -> None:
+        object.__setattr__(self, "_module_name", module_name)
+        object.__setattr__(self, "_extra", extra)
+
+    def _raise(self) -> None:
+        module_name = object.__getattribute__(self, "_module_name")
+        extra = object.__getattribute__(self, "_extra")
+        raise ImportError(
+            f"'{module_name}' is required for this feature. "
+            f"Install with: pip install agentloom[{extra}]"
+        )
+
+    def __getattr__(self, name: str) -> None:
+        self._raise()
+
+    def __call__(self, *args: object, **kwargs: object) -> None:
+        self._raise()
+
+    def __bool__(self) -> bool:
+        return False
+
+
+def try_import(module_name: str, extra: str = "all") -> ModuleType | MissingDependencyProxy:
+    """Try to import a module, returning a proxy if it's not installed.
+
+    Args:
+        module_name: Fully qualified module name (e.g., "opentelemetry.sdk").
+        extra: The pip extra that provides this module (e.g., "observability").
+
+    Returns:
+        The real module if available, or a MissingDependencyProxy.
+    """
+    try:
+        return importlib.import_module(module_name)
+    except ImportError:
+        return MissingDependencyProxy(module_name, extra)
+
+
+def is_available(module_or_proxy: ModuleType | MissingDependencyProxy) -> bool:
+    """Check if a try_import result is a real module (True) or a proxy (False)."""
+    return not isinstance(module_or_proxy, MissingDependencyProxy)

agentloom/config.py

@@ -0,0 +1,55 @@
+"""Global configuration for AgentLoom."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class ProviderConfig(BaseModel):
+    """Configuration for a single LLM provider."""
+
+    name: str
+    api_key: str = ""
+    base_url: str = ""
+    models: list[str] = Field(default_factory=list)
+    priority: int = 0
+    is_fallback: bool = False
+    max_retries: int = 3
+    timeout: float = 30.0
+
+
+class AgentLoomConfig(BaseModel):
+    """Global configuration, loaded from env vars or config file."""
+
+    log_level: str = "INFO"
+    log_format: str = "json"  # "json" or "text"
+    observability_enabled: bool = True
+    default_provider: str = "openai"
+    max_concurrent_steps: int = 10
+    budget_limit_usd: float | None = None
+    checkpoint_enabled: bool = False
+    checkpoint_dir: str = ".agentloom/checkpoints"
+    providers: list[ProviderConfig] = Field(default_factory=list)
+
+
+# TODO: support AGENTLOOM_ env var prefix (pydantic-settings would be nice here)
+def load_config(config_path: str | None = None) -> AgentLoomConfig:
+    """Load configuration from a YAML file or return defaults.
+
+    Args:
+        config_path: Path to agentloom.yaml config file.
+
+    Returns:
+        Validated AgentLoomConfig instance.
+    """
+    if config_path is None:
+        return AgentLoomConfig()
+
+    from pathlib import Path
+
+    import yaml  # noqa: TCH002
+
+    raw = yaml.safe_load(Path(config_path).read_text())
+    if raw is None:
+        return AgentLoomConfig()
+    return AgentLoomConfig.model_validate(raw)

agentloom/core/__init__.py

@@ -0,0 +1 @@
+"""Core workflow engine components."""