aptdata 0.0.2__tar.gz → 0.1.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aptdata
-Version: 0.0.2
+Version: 0.1.0
 Summary: A declarative, extensible framework for building smart data pipelines in Python
 License: MIT
 License-File: LICENSE
@@ -17,12 +17,13 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Provides-Extra: ai
 Provides-Extra: all
 Provides-Extra: pandas
 Provides-Extra: plugins
 Provides-Extra: spark
 Requires-Dist: httpx (>=0.27,<0.28) ; extra == "plugins" or extra == "all"
-Requires-Dist: mcp (>=1.26.0,<2.0.0)
+Requires-Dist: mcp (>=1.26.0,<2.0.0) ; extra == "ai" or extra == "all"
 Requires-Dist: opentelemetry-api (>=1.40.0,<2.0.0)
 Requires-Dist: opentelemetry-sdk (>=1.40.0,<2.0.0)
 Requires-Dist: pandas (>=2.2,<3.0) ; extra == "pandas" or extra == "all"
@@ -44,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)
 
 ---
 
@@ -95,6 +96,7 @@ pip install aptdata
 pip install aptdata[pandas]   # pandas support
 pip install aptdata[spark]    # PySpark support
 pip install aptdata[plugins]  # REST, PostgreSQL, Parquet I/O
+pip install aptdata[ai]       # MCP server for AI agents
 pip install aptdata[all]      # everything
 ```
 
@@ -273,6 +275,23 @@ See [Governance docs](docs/governance.md) for the full API.
 
 ---
 
+## AI Agents & MCP Server
+
+aptdata ships with a built-in [Model Context Protocol](https://modelcontextprotocol.io/) server (`mcp-start`). This transforms AI assistants (like Claude, Copilot, or Devin) into autonomous data engineers with direct access to:
+
+- **Pipeline Execution:** Trigger and monitor data flows (`run_flow`).
+- **Data Quality:** Audit the latest quality test results (`quality://reports/...`).
+- **Data Governance:** Read business rules to prevent violations (`governance://rules`).
+- **Lineage:** Trace upstream dependencies and column-level provenance (`get_pipeline_lineage`).
+
+```bash
+aptdata mcp-start --transport stdio
+```
+
+See the [MCP Documentation](docs/mcp.md) for setup instructions.
+
+---
+
 ## Release process
 
 Releases are automated via the [Release workflow](.github/workflows/release.yml).

{aptdata-0.0.2 → 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)
 
 ---
 
@@ -51,6 +51,7 @@ pip install aptdata
 pip install aptdata[pandas]   # pandas support
 pip install aptdata[spark]    # PySpark support
 pip install aptdata[plugins]  # REST, PostgreSQL, Parquet I/O
+pip install aptdata[ai]       # MCP server for AI agents
 pip install aptdata[all]      # everything
 ```
 
@@ -229,6 +230,23 @@ See [Governance docs](docs/governance.md) for the full API.
 
 ---
 
+## AI Agents & MCP Server
+
+aptdata ships with a built-in [Model Context Protocol](https://modelcontextprotocol.io/) server (`mcp-start`). This transforms AI assistants (like Claude, Copilot, or Devin) into autonomous data engineers with direct access to:
+
+- **Pipeline Execution:** Trigger and monitor data flows (`run_flow`).
+- **Data Quality:** Audit the latest quality test results (`quality://reports/...`).
+- **Data Governance:** Read business rules to prevent violations (`governance://rules`).
+- **Lineage:** Trace upstream dependencies and column-level provenance (`get_pipeline_lineage`).
+
+```bash
+aptdata mcp-start --transport stdio
+```
+
+See the [MCP Documentation](docs/mcp.md) for setup instructions.
+
+---
+
 ## Release process
 
 Releases are automated via the [Release workflow](.github/workflows/release.yml).

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

@@ -1,3 +1,3 @@
 """aptdata: A framework for smart data pipelines."""
 
-__version__ = "0.0.2"
+__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