aptdata 0.0.3__tar.gz → 0.1.0__tar.gz

{aptdata-0.0.3 → aptdata-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aptdata
-Version: 0.0.3
+Version: 0.1.0
 Summary: A declarative, extensible framework for building smart data pipelines in Python
 License: MIT
 License-File: LICENSE
@@ -45,11 +45,11 @@ Description-Content-Type: text/markdown
 
 # aptdata
 
-> **v0.0.2** · A declarative, extensible framework for building smart data pipelines in Python.
+> **v0.0.3** · A declarative, extensible framework for building smart data pipelines in Python.
 
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
-[![Version](https://img.shields.io/badge/version-0.0.2-orange)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.0.3-orange)](CHANGELOG.md)
 
 ---
 

{aptdata-0.0.3 → aptdata-0.1.0}/README.md

@@ -1,10 +1,10 @@
 # aptdata
 
-> **v0.0.2** · A declarative, extensible framework for building smart data pipelines in Python.
+> **v0.0.3** · A declarative, extensible framework for building smart data pipelines in Python.
 
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
-[![Version](https://img.shields.io/badge/version-0.0.2-orange)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.0.3-orange)](CHANGELOG.md)
 
 ---
 

{aptdata-0.0.3 → aptdata-0.1.0}/aptdata/__init__.py

@@ -1,3 +1,3 @@
 """aptdata: A framework for smart data pipelines."""
 
-__version__ = "0.0.3"
+__version__ = "0.1.0"

aptdata-0.1.0/aptdata/agents/__init__.py

@@ -0,0 +1,49 @@
+"""aptdata.agents — uniform interface over heterogeneous agent backends.
+
+The single source of truth for the multi-agent ecosystem: one declarative
+registry (``agents.yaml``), one :class:`IAgent` contract, one adapter per
+backend kind.
+"""
+
+from __future__ import annotations
+
+from aptdata.agents.base import (
+    AgentHealth,
+    AgentResponse,
+    AgentSpec,
+    BaseAgent,
+    IAgent,
+)
+from aptdata.agents.cli_agents import ClaudeCodeAgent, CLIAgent, OpenCodeAgent
+from aptdata.agents.openclaw import OpenClawAgent
+from aptdata.agents.project import (
+    Project,
+    ProjectRunner,
+    Task,
+    TaskResult,
+    scaffold_project,
+)
+from aptdata.agents.registry import ADAPTERS, AgentRegistry
+from aptdata.agents.router import RouteDecision, Router, Skill
+
+__all__ = [
+    "ADAPTERS",
+    "AgentHealth",
+    "AgentRegistry",
+    "AgentResponse",
+    "AgentSpec",
+    "BaseAgent",
+    "CLIAgent",
+    "ClaudeCodeAgent",
+    "IAgent",
+    "OpenClawAgent",
+    "OpenCodeAgent",
+    "Project",
+    "ProjectRunner",
+    "RouteDecision",
+    "Router",
+    "Skill",
+    "Task",
+    "TaskResult",
+    "scaffold_project",
+]

aptdata-0.1.0/aptdata/agents/base.py

@@ -0,0 +1,158 @@
+"""Agents — a uniform interface over heterogeneous AI/automation backends.
+
+This module lets aptdata talk to many kinds of agent backends (OpenClaw
+workers, OpenCode, Claude Code, plain HTTP APIs) through a single, stable
+contract, mirroring the :mod:`aptdata.integrations` pattern.
+
+* :class:`AgentSpec` — declarative description of one backend (loaded from
+  ``agents.yaml``); the single source of truth that replaces the three
+  divergent registries (multiverso.json, plugin schema.yaml, app.py).
+* :class:`IAgent` / :class:`BaseAgent` — the interface every adapter
+  implements, following the project's ``IXxx`` -> ``BaseXxx`` convention.
+* :class:`AgentResponse` — a machine-readable result, JSON-friendly like the
+  rest of aptdata's outputs.
+
+Design goals
+------------
+* **Single source of truth** — one registry, many consumers.
+* **Adapter per backend** — each backend's quirks are isolated in one class.
+* **No global state** — specs are passed in explicitly at construction.
+"""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Declarative spec — the single source of truth
+# ---------------------------------------------------------------------------
+
+
+class AgentSpec(BaseModel):
+    """Declarative description of a single agent backend.
+
+    Loaded from ``agents.yaml``. Carries enough metadata for the registry to
+    route to it and for an adapter to reach it, without any consumer needing
+    to know how the backend works internally.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: str
+    name: str
+    type: str  # adapter kind: openclaw | opencode | claude_code | http
+    location: str = "local"  # local | vps
+    enabled: bool = True
+    role: str = "worker"
+    handle: str | None = None  # Telegram handle, if any
+    model: str | None = None
+    capabilities: list[str] = Field(default_factory=list)
+
+    # Transport (optional — only some adapters use these)
+    host: str | None = None
+    port: int | None = None
+    endpoint: str | None = None
+    timeout_ms: int = 30000
+    weight: int = 5
+
+    note: str = ""
+
+    @property
+    def base_url(self) -> str | None:
+        """HTTP base URL for adapters that speak over the network."""
+        if self.host and self.port:
+            return f"http://{self.host}:{self.port}"
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Status + response value objects
+# ---------------------------------------------------------------------------
+
+
+class AgentHealth(str, Enum):
+    """Coarse liveness of a backend."""
+
+    UP = "up"
+    DOWN = "down"
+    DISABLED = "disabled"
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class AgentResponse:
+    """Result of sending a prompt to an agent.
+
+    JSON-serialisable so it fits aptdata's machine-readable output contract.
+    """
+
+    ok: bool
+    agent_id: str
+    text: str = ""
+    error: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "ok": self.ok,
+            "agent_id": self.agent_id,
+            "text": self.text,
+            "error": self.error,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Interface + base
+# ---------------------------------------------------------------------------
+
+
+class IAgent(ABC):
+    """Uniform interface every backend adapter implements."""
+
+    @abstractmethod
+    def send(self, prompt: str, **kwargs: Any) -> AgentResponse:
+        """Send a prompt/instruction and return the backend's reply."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def health(self) -> AgentHealth:
+        """Report coarse liveness without side effects on the conversation."""
+        raise NotImplementedError
+
+
+class BaseAgent(IAgent):
+    """Common behaviour shared by adapters; holds the declarative spec."""
+
+    #: adapter kind this class handles; subclasses override.
+    type: str = "base"
+
+    def __init__(self, spec: AgentSpec) -> None:
+        self.spec = spec
+
+    @property
+    def id(self) -> str:
+        return self.spec.id
+
+    @property
+    def capabilities(self) -> list[str]:
+        return self.spec.capabilities
+
+    def supports(self, capability: str) -> bool:
+        return capability in self.spec.capabilities
+
+    def health(self) -> AgentHealth:
+        if not self.spec.enabled:
+            return AgentHealth.DISABLED
+        return AgentHealth.UNKNOWN
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return f"<{self.__class__.__name__} id={self.spec.id!r} type={self.type!r}>"

aptdata-0.1.0/aptdata/agents/cli_agents.py

@@ -0,0 +1,99 @@
+"""CLI-backed agent adapters — Claude Code and OpenCode.
+
+Unlike OpenClaw (which speaks a gateway protocol), these backends are driven
+through their command-line interface as stateless one-shot dispatches:
+
+* :class:`ClaudeCodeAgent` — ``claude -p "<prompt>"`` (print mode).
+* :class:`OpenCodeAgent` — ``opencode run "<prompt>"``.
+
+Each invocation spawns a fresh session (no shared conversation), which keeps
+dispatch stateless and safe. The prompt is always passed as an argv element
+(never through a shell) so its content can't inject commands.
+"""
+
+from __future__ import annotations
+
+import logging
+import shutil
+import subprocess
+from typing import Any
+
+from aptdata.agents.base import AgentHealth, AgentResponse, BaseAgent
+
+logger = logging.getLogger(__name__)
+
+
+class CLIAgent(BaseAgent):
+    """Common machinery for agents driven by a local CLI binary."""
+
+    #: the executable this adapter shells out to; subclasses set it.
+    binary: str = ""
+
+    def _build_command(self, prompt: str) -> list[str]:
+        """Return the argv list to run for *prompt*. Subclasses implement."""
+        raise NotImplementedError
+
+    def send(self, prompt: str, **kwargs: Any) -> AgentResponse:
+        if not self.spec.enabled:
+            return AgentResponse(ok=False, agent_id=self.id, error="agent disabled")
+        if shutil.which(self.binary) is None:
+            return AgentResponse(
+                ok=False, agent_id=self.id, error=f"'{self.binary}' not found in PATH"
+            )
+
+        cmd = self._build_command(prompt)
+        try:
+            proc = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=self.spec.timeout_ms / 1000,
+                check=False,
+            )
+        except subprocess.TimeoutExpired:
+            return AgentResponse(
+                ok=False, agent_id=self.id, error="timeout"
+            )
+        except OSError as exc:  # pragma: no cover - defensive
+            return AgentResponse(ok=False, agent_id=self.id, error=str(exc))
+
+        if proc.returncode != 0:
+            return AgentResponse(
+                ok=False,
+                agent_id=self.id,
+                error=(proc.stderr or proc.stdout or "non-zero exit").strip()[:500],
+            )
+        return AgentResponse(
+            ok=True, agent_id=self.id, text=proc.stdout.strip()
+        )
+
+    def health(self) -> AgentHealth:
+        if not self.spec.enabled:
+            return AgentHealth.DISABLED
+        return AgentHealth.UP if shutil.which(self.binary) else AgentHealth.DOWN
+
+
+class ClaudeCodeAgent(CLIAgent):
+    """Dispatches to Claude Code via ``claude -p``."""
+
+    type = "claude_code"
+    binary = "claude"
+
+    def _build_command(self, prompt: str) -> list[str]:
+        cmd = ["claude", "-p", prompt]
+        if self.spec.model:
+            cmd += ["--model", self.spec.model]
+        return cmd
+
+
+class OpenCodeAgent(CLIAgent):
+    """Dispatches to OpenCode via ``opencode run``."""
+
+    type = "opencode"
+    binary = "opencode"
+
+    def _build_command(self, prompt: str) -> list[str]:
+        cmd = ["opencode", "run", prompt]
+        if self.spec.model:
+            cmd += ["-m", self.spec.model]
+        return cmd

aptdata-0.1.0/aptdata/agents/openclaw.py

@@ -0,0 +1,95 @@
+"""OpenClaw backend adapter.
+
+OpenClaw workers (Zeca, Ondina, Maresia, Hermez, ...) expose an HTTP chat
+endpoint (default ``/api/chat`` on ports 48330-48333). This adapter isolates
+that transport so the rest of aptdata only ever sees :class:`IAgent`.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from aptdata.agents.base import AgentHealth, AgentResponse, BaseAgent
+
+logger = logging.getLogger(__name__)
+
+
+class OpenClawAgent(BaseAgent):
+    """Talks to an OpenClaw worker over HTTP."""
+
+    type = "openclaw"
+
+    def _endpoint(self) -> str | None:
+        base = self.spec.base_url
+        if not base:
+            return None
+        path = self.spec.endpoint or "/api/chat"
+        return f"{base}{path}"
+
+    def send(self, prompt: str, **kwargs: Any) -> AgentResponse:
+        if not self.spec.enabled:
+            return AgentResponse(
+                ok=False, agent_id=self.id, error="agent disabled"
+            )
+
+        url = self._endpoint()
+        if not url:
+            return AgentResponse(
+                ok=False,
+                agent_id=self.id,
+                error="no host/port configured for OpenClaw agent",
+            )
+
+        import requests  # lazy: keeps core import-light, mirrors integrations/
+
+        payload = {"message": prompt, **kwargs}
+        try:
+            resp = requests.post(
+                url, json=payload, timeout=self.spec.timeout_ms / 1000
+            )
+        except requests.RequestException as exc:
+            logger.warning("OpenClaw %s unreachable: %s", self.id, exc)
+            return AgentResponse(ok=False, agent_id=self.id, error=str(exc))
+
+        if resp.status_code != 200:
+            return AgentResponse(
+                ok=False,
+                agent_id=self.id,
+                error=f"HTTP {resp.status_code}",
+                raw={"status": resp.status_code, "body": resp.text[:500]},
+            )
+
+        data = self._parse(resp)
+        text = self._extract_text(data)
+        return AgentResponse(ok=True, agent_id=self.id, text=text, raw=data)
+
+    @staticmethod
+    def _parse(resp: Any) -> dict[str, Any]:
+        try:
+            data = resp.json()
+            return data if isinstance(data, dict) else {"value": data}
+        except ValueError:
+            return {"text": resp.text}
+
+    @staticmethod
+    def _extract_text(data: dict[str, Any]) -> str:
+        for key in ("reply", "response", "message", "text", "output"):
+            value = data.get(key)
+            if isinstance(value, str):
+                return value
+        return ""
+
+    def health(self) -> AgentHealth:
+        if not self.spec.enabled:
+            return AgentHealth.DISABLED
+        url = self.spec.base_url
+        if not url:
+            return AgentHealth.UNKNOWN
+        import requests
+
+        try:
+            resp = requests.get(url, timeout=3)
+            return AgentHealth.UP if resp.status_code < 500 else AgentHealth.DOWN
+        except requests.RequestException:
+            return AgentHealth.DOWN

aptdata-0.1.0/aptdata/agents/project.py

@@ -0,0 +1,180 @@
+"""Projects — a project is a Flow of agent tasks.
+
+This is the bridge between aptdata's orchestration model and the multi-agent
+ecosystem: a :class:`Project` is a declarative plan (a list of :class:`Task`),
+and :class:`ProjectRunner` executes it by routing each task to the right agent
+via the :class:`~aptdata.agents.router.Router`.
+
+A project is persisted as ``<name>.project.yaml`` — editable by hand, runnable
+by ``aptdata project run``. Each task can pin an explicit ``agent``, ask for a
+``capability`` (routed to the best agent), or fall back to skill routing on its
+``prompt``. ``depends_on`` lets a task be skipped when an upstream task fails.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import BaseModel, Field
+
+from aptdata.agents.router import Router
+
+logger = logging.getLogger(__name__)
+
+
+class Task(BaseModel):
+    """One step of a project, dispatched to a single agent."""
+
+    id: str
+    prompt: str
+    capability: str | None = None  # route by capability
+    agent: str | None = None  # pin an explicit agent (wins over capability)
+    depends_on: list[str] = Field(default_factory=list)
+
+
+class Project(BaseModel):
+    """A declarative plan: an ordered list of agent tasks."""
+
+    name: str
+    description: str = ""
+    tasks: list[Task] = Field(default_factory=list)
+
+    @classmethod
+    def from_yaml(cls, path: str | Path) -> Project:
+        raw = yaml.safe_load(Path(path).read_text(encoding="utf-8")) or {}
+        return cls(**raw)
+
+    def to_yaml(self, path: str | Path) -> None:
+        data = self.model_dump(exclude_defaults=False)
+        Path(path).write_text(
+            yaml.safe_dump(data, allow_unicode=True, sort_keys=False),
+            encoding="utf-8",
+        )
+
+
+@dataclass
+class TaskResult:
+    """Outcome of running a single task."""
+
+    task_id: str
+    agent_id: str | None
+    mode: str
+    ok: bool
+    text: str = ""
+    error: str | None = None
+    skipped: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "task_id": self.task_id,
+            "agent_id": self.agent_id,
+            "mode": self.mode,
+            "ok": self.ok,
+            "skipped": self.skipped,
+            "error": self.error,
+        }
+
+
+class ProjectRunner:
+    """Executes a :class:`Project` by routing every task through the Router."""
+
+    def __init__(self, project: Project, router: Router) -> None:
+        self.project = project
+        self.router = router
+
+    def _route_task(self, task: Task):
+        """Decide which agent handles a task (explicit > capability > skill)."""
+        from aptdata.agents.router import RouteDecision  # noqa: PLC0415
+
+        if task.agent:
+            if task.agent in self.router.registry:
+                return RouteDecision(
+                    agent_id=task.agent, mode="explicit", text=task.prompt,
+                    confidence=1.0,
+                )
+            return RouteDecision(agent_id=None, mode="none", text=task.prompt)
+        if task.capability:
+            agent = self.router.registry.resolve(task.capability)
+            if agent:
+                return RouteDecision(
+                    agent_id=agent.id, mode="capability", text=task.prompt,
+                    confidence=0.9,
+                )
+        return self.router.route(task.prompt)
+
+    def plan(self) -> list[TaskResult]:
+        """Dry-run: resolve routing for every task without sending anything."""
+        results: list[TaskResult] = []
+        for task in self.project.tasks:
+            decision = self._route_task(task)
+            results.append(
+                TaskResult(
+                    task_id=task.id,
+                    agent_id=decision.agent_id,
+                    mode=decision.mode,
+                    ok=decision.agent_id is not None,
+                )
+            )
+        return results
+
+    def run(self) -> list[TaskResult]:
+        """Execute tasks in order, skipping those whose dependencies failed."""
+        results: dict[str, TaskResult] = {}
+        for task in self.project.tasks:
+            failed_dep = next(
+                (
+                    d
+                    for d in task.depends_on
+                    if d not in results or not results[d].ok
+                ),
+                None,
+            )
+            if failed_dep is not None:
+                results[task.id] = TaskResult(
+                    task_id=task.id, agent_id=None, mode="skipped", ok=False,
+                    skipped=True, error=f"dependency '{failed_dep}' unmet",
+                )
+                continue
+
+            decision = self._route_task(task)
+            if decision.agent_id is None:
+                results[task.id] = TaskResult(
+                    task_id=task.id, agent_id=None, mode=decision.mode, ok=False,
+                    error="no agent could be routed",
+                )
+                continue
+
+            response = self.router.registry.get(decision.agent_id).send(
+                decision.text
+            )
+            results[task.id] = TaskResult(
+                task_id=task.id,
+                agent_id=decision.agent_id,
+                mode=decision.mode,
+                ok=response.ok,
+                text=response.text,
+                error=response.error,
+            )
+        return [results[t.id] for t in self.project.tasks]
+
+
+def scaffold_project(name: str) -> Project:
+    """Return a starter project with example tasks across capabilities."""
+    return Project(
+        name=name,
+        description=f"Projeto {name} — orquestrado pelo aptdata.",
+        tasks=[
+            Task(id="planejar", prompt=f"Faz o plano técnico do {name}.",
+                 capability="planning"),
+            Task(id="backend", prompt="Implementa o backend / API.",
+                 capability="backend", depends_on=["planejar"]),
+            Task(id="frontend", prompt="Implementa a interface.",
+                 capability="frontend", depends_on=["planejar"]),
+            Task(id="deploy", prompt="Sobe em produção.",
+                 capability="deploy", depends_on=["backend", "frontend"]),
+        ],
+    )