agentdna-sdk 0.2.0__py3-none-any.whl

agentdna/__init__.py

@@ -0,0 +1,85 @@
+"""
+🧬 AgentDNA — Sentry for AI Agents
+
+One-line observability for any Python agent.
+No framework required. No API key. No network calls.
+
+Usage:
+    from agentdna import observe, get_stats
+
+    @observe
+    def my_agent(prompt):
+        return llm.call(prompt)
+
+    # Check stats anytime (persists across restarts)
+    print(get_stats())
+
+    # Or use the CLI:
+    #   agentdna stats
+    #   agentdna stats my_agent
+"""
+
+__version__ = "0.2.0"
+
+# ⭐ Primary exports — zero dependencies (uses only stdlib sqlite3)
+from agentdna.plugins.observe import observe, get_stats, reset_stats, export_stats
+
+# Everything else is lazy-imported to avoid requiring httpx/PyYAML
+# for users who only want observability.
+
+
+def __getattr__(name: str):
+    """Lazy imports — only load when actually used."""
+    _lazy = {
+        # Models
+        "Agent": ("agentdna.models", "Agent"),
+        "AgentSearchResult": ("agentdna.models", "AgentSearchResult"),
+        "Capability": ("agentdna.models", "Capability"),
+        "Pricing": ("agentdna.models", "Pricing"),
+        "TrustScore": ("agentdna.models", "TrustScore"),
+        "TaskResult": ("agentdna.models", "TaskResult"),
+        # Registry
+        "register_agent": ("agentdna.registry", "register_agent"),
+        "load_agent_card": ("agentdna.registry", "load_agent_card"),
+        "generate_agent_card": ("agentdna.registry", "generate_agent_card"),
+        # Discovery
+        "find_agent": ("agentdna.discovery", "find_agent"),
+        "search_agents": ("agentdna.discovery", "search_agents"),
+        # Marketplace
+        "hire_agent": ("agentdna.marketplace", "hire_agent"),
+        "hire_agent_sync": ("agentdna.marketplace", "hire_agent_sync"),
+        # Client
+        "AgentDNAClient": ("agentdna.client", "AgentDNAClient"),
+    }
+
+    if name in _lazy:
+        module_path, attr_name = _lazy[name]
+        from importlib import import_module
+        mod = import_module(module_path)
+        return getattr(mod, attr_name)
+
+    raise AttributeError(f"module 'agentdna' has no attribute {name!r}")
+
+
+__all__ = [
+    # ⭐ Core — observability (zero dependencies)
+    "observe",
+    "get_stats",
+    "reset_stats",
+    "export_stats",
+    # Everything else (lazy, requires httpx/PyYAML)
+    "AgentDNAClient",
+    "Agent",
+    "AgentSearchResult",
+    "Capability",
+    "Pricing",
+    "TrustScore",
+    "TaskResult",
+    "register_agent",
+    "load_agent_card",
+    "generate_agent_card",
+    "find_agent",
+    "search_agents",
+    "hire_agent",
+    "hire_agent_sync",
+]

agentdna/cli.py

@@ -0,0 +1,274 @@
+#!/usr/bin/env python3
+"""
+🧬 AgentDNA CLI — Sentry for AI Agents
+
+Usage:
+    agentdna stats [func]                View observability stats
+    agentdna stats --reset [func]        Reset stats
+    agentdna stats --export json         Export stats
+    agentdna search <query>              Search for agents
+    agentdna register [path]             Register your agent
+    agentdna init [name]                 Generate agentdna.yaml
+    agentdna trust <agent-id>            View trust score
+    agentdna status <agent-id>           Check agent health
+    agentdna review <agent-id>           Submit a review
+"""
+
+import sys
+
+import click
+
+_CLI_VERSION = "0.2.0"
+
+
+@click.group()
+@click.version_option(version=_CLI_VERSION)
+def cli():
+    """🧬 AgentDNA — Sentry for AI Agents"""
+    pass
+
+
+# --- Stats Command (the money maker) ---
+
+@cli.command()
+@click.argument("func_name", required=False, default=None)
+@click.option("--reset", is_flag=True, help="Reset stats for this function (or all)")
+@click.option("--export", "export_format", type=click.Choice(["json", "csv"]), help="Export format")
+@click.option("--db", "db_path", help="Path to SQLite database")
+def stats(func_name, reset, export_format, db_path):
+    """📊 View observability stats for your agents."""
+    import os
+    if db_path:
+        os.environ["AGENTDNA_DB_PATH"] = db_path
+
+    from agentdna.plugins.observe import get_stats, reset_stats, export_stats
+
+    if reset:
+        if func_name:
+            reset_stats(func_name)
+            click.echo(f"✅ Reset stats for: {func_name}")
+        else:
+            reset_stats()
+            click.echo("✅ Reset all stats")
+        return
+
+    if export_format:
+        output = export_stats(func_name, format=export_format)
+        click.echo(output)
+        return
+
+    data = get_stats(func_name)
+
+    if not data:
+        click.echo("📊 No data yet. Add @observe to your agent functions first.")
+        click.echo()
+        click.echo("  from agentdna import observe")
+        click.echo()
+        click.echo("  @observe")
+        click.echo("  def my_agent(prompt):")
+        click.echo("      return result")
+        return
+
+    # Single function stats
+    if func_name and isinstance(data, dict) and "total_calls" in data:
+        _print_stats(func_name, data)
+        return
+
+    # All functions
+    click.echo(f"\n📊 AgentDNA — {len(data)} observed function(s)\n")
+    for name, s in data.items():
+        _print_stats(name, s, compact=True)
+    click.echo()
+
+
+def _print_stats(name: str, s: dict, compact: bool = False):
+    """Pretty-print stats for a function."""
+    total = s.get("total_calls", 0)
+    success_rate = s.get("success_rate", 0)
+    avg_latency = s.get("avg_latency_ms", 0)
+    p50 = s.get("p50_latency_ms", 0)
+    p95 = s.get("p95_latency_ms", 0)
+    p99 = s.get("p99_latency_ms", 0)
+    failed = s.get("failed_calls", 0)
+    errors = s.get("error_types", {})
+    first = s.get("first_seen", "?")
+    last = s.get("last_seen", "?")
+
+    # Health indicator
+    if success_rate >= 0.95:
+        health = "✅ Healthy"
+    elif success_rate >= 0.80:
+        health = "⚠️  Degraded"
+    else:
+        health = "🔴 Unhealthy"
+
+    if compact:
+        bar = "█" * int(success_rate * 10) + "░" * (10 - int(success_rate * 10))
+        click.echo(f"  📌 {name}")
+        click.echo(f"     {health}  {total} calls  {bar} {success_rate:.0%}  avg {avg_latency:.0f}ms")
+        if failed:
+            click.echo(f"     ❌ {failed} failures: {', '.join(f'{k}({v})' for k, v in errors.items())}")
+        click.echo()
+    else:
+        click.echo(f"\n📊 Stats: {name}")
+        click.echo(f"{'━' * 45}")
+        click.echo(f"  Health:           {health}")
+        click.echo(f"  Total calls:      {total}")
+        click.echo(f"  Success rate:     {success_rate:.1%}")
+        click.echo(f"  Failed calls:     {failed}")
+        click.echo(f"{'━' * 45}")
+        click.echo(f"  Avg latency:      {avg_latency:.1f} ms")
+        click.echo(f"  P50 latency:      {p50:.1f} ms")
+        click.echo(f"  P95 latency:      {p95:.1f} ms")
+        click.echo(f"  P99 latency:      {p99:.1f} ms")
+        if errors:
+            click.echo(f"{'━' * 45}")
+            click.echo(f"  Errors:")
+            for err_type, count in errors.items():
+                click.echo(f"    {err_type}: {count}")
+        click.echo(f"{'━' * 45}")
+        click.echo(f"  First seen:       {first}")
+        click.echo(f"  Last seen:        {last}")
+        click.echo()
+
+
+# --- Search Command ---
+
+@cli.command()
+@click.argument("query")
+@click.option("--language", "-l", help="Filter by language (e.g., en, zh)")
+@click.option("--max-price", "-p", type=float, help="Maximum price per unit")
+@click.option("--min-trust", "-t", type=float, help="Minimum trust score (0-100)")
+@click.option("--verified", is_flag=True, help="Only show verified agents")
+@click.option("--protocol", type=click.Choice(["a2a", "mcp", "any"]), default="any")
+@click.option("--limit", "-n", default=10, help="Number of results")
+@click.option("--json", "output_json", is_flag=True, help="Output as JSON")
+def search(query, language, max_price, min_trust, verified, protocol, limit, output_json):
+    """Search for agents by capability."""
+    from agentdna.discovery import search_agents
+
+    results = search_agents(
+        skill=query,
+        language=language,
+        max_price=max_price,
+        min_reputation=min_trust,
+        verified=verified,
+        protocol=protocol if protocol != "any" else None,
+        limit=limit,
+    )
+
+    if output_json:
+        import json
+        from dataclasses import asdict
+        click.echo(json.dumps([asdict(a) for a in results.agents], indent=2, default=str))
+        return
+
+    if not results.agents:
+        click.echo(f"No agents found for: {query}")
+        return
+
+    click.echo(f"\n🧬 Found {results.total} agents for '{query}':\n")
+    for agent in results.agents:
+        score = agent.trust_score.total if agent.trust_score else "?"
+        verified_badge = " 🏆" if agent.verified else ""
+        click.echo(f"  {agent.name} v{agent.version}  (DNA: {score}/100){verified_badge}")
+        click.echo(f"  ID: {agent.id}")
+        click.echo(f"  {agent.description}")
+        for cap in agent.capabilities:
+            price = cap.pricing.display() if cap.pricing else "N/A"
+            langs = ", ".join(cap.languages) if cap.languages else "any"
+            click.echo(f"    → {cap.skill} ({price}) [{langs}]")
+        click.echo()
+
+
+# --- Register Command ---
+
+@cli.command()
+@click.argument("path", default="./agentdna.yaml")
+def register(path):
+    """Register your agent in the AgentDNA registry."""
+    from agentdna.registry import register_agent
+
+    try:
+        result = register_agent(path)
+        click.echo(f"✅ Registered: {result.get('agent_id', 'success')}")
+    except FileNotFoundError:
+        click.echo(f"❌ File not found: {path}")
+        click.echo("Run 'agentdna init' to create one.")
+        sys.exit(1)
+    except Exception as e:
+        click.echo(f"❌ Registration failed: {e}")
+        sys.exit(1)
+
+
+# --- Init Command ---
+
+@cli.command()
+@click.argument("name", default="MyAgent")
+@click.option("--output", "-o", default="./agentdna.yaml", help="Output file path")
+def init(name, output):
+    """Generate a starter agentdna.yaml file."""
+    from agentdna.registry import generate_agent_card
+
+    path = generate_agent_card(name=name, output_path=output)
+    click.echo(f"✅ Created agent card: {path}")
+    click.echo("Edit it with your agent's details, then run: agentdna register")
+
+
+# --- Trust Command ---
+
+@cli.command()
+@click.argument("agent_id")
+def trust(agent_id):
+    """View the trust score for an agent."""
+    from agentdna.client import AgentDNAClient
+
+    with AgentDNAClient() as client:
+        score = client.get_trust_score(agent_id)
+
+    click.echo(f"\n🧬 Trust Score: {agent_id}\n")
+    click.echo(f"  Total:                {score.get('total', 0)}/100")
+    click.echo(f"  Task Completion:      {score.get('task_completion', 0)}/40")
+    click.echo(f"  Response Quality:     {score.get('response_quality', 0)}/25")
+    click.echo(f"  Latency Reliability:  {score.get('latency_reliability', 0)}/15")
+    click.echo(f"  Uptime:               {score.get('uptime_score', 0)}/10")
+    click.echo(f"  Verification:         {score.get('verification_bonus', 0)}/10")
+
+
+# --- Status Command ---
+
+@cli.command()
+@click.argument("agent_id")
+def status(agent_id):
+    """Check agent health status."""
+    from agentdna.client import AgentDNAClient
+
+    with AgentDNAClient() as client:
+        info = client.get_agent(agent_id)
+
+    click.echo(f"\n🧬 Agent Status: {agent_id}\n")
+    click.echo(f"  Name:     {info.get('name', 'Unknown')}")
+    click.echo(f"  Version:  {info.get('version', 'Unknown')}")
+    click.echo(f"  Status:   {'🟢 Online' if info.get('online') else '🔴 Offline'}")
+    click.echo(f"  Uptime:   {info.get('uptime', 'Unknown')}")
+    click.echo(f"  Tasks:    {info.get('total_tasks_completed', 0)} completed")
+
+
+# --- Review Command ---
+
+@cli.command()
+@click.argument("agent_id")
+@click.option("--rating", "-r", type=click.IntRange(1, 5), prompt="Rating (1-5)")
+@click.option("--comment", "-c", prompt="Review comment")
+def review(agent_id, rating, comment):
+    """Submit a review for an agent."""
+    from agentdna.client import AgentDNAClient
+
+    with AgentDNAClient() as client:
+        client.submit_review(agent_id, rating, comment)
+
+    click.echo(f"✅ Review submitted for {agent_id}")
+
+
+if __name__ == "__main__":
+    cli()

agentdna/client.py

@@ -0,0 +1,125 @@
+"""AgentDNA API client."""
+
+import os
+from typing import Optional
+
+import httpx
+
+AGENTDNA_API_URL = os.environ.get("AGENTDNA_API_URL", "https://api.agentdna.dev")
+AGENTDNA_API_KEY = os.environ.get("AGENTDNA_API_KEY", "")
+
+
+class AgentDNAClient:
+    """Client for the AgentDNA registry API."""
+
+    def __init__(
+        self,
+        api_url: str = AGENTDNA_API_URL,
+        api_key: str = AGENTDNA_API_KEY,
+    ):
+        self.api_url = api_url.rstrip("/")
+        self.api_key = api_key
+        self._client = httpx.Client(
+            base_url=self.api_url,
+            headers={
+                "Authorization": f"Bearer {self.api_key}" if self.api_key else "",
+                "Content-Type": "application/json",
+                "User-Agent": "agentdna-python/0.1.0",
+            },
+            timeout=30.0,
+        )
+
+    def _get(self, path: str, params: Optional[dict] = None) -> dict:
+        resp = self._client.get(path, params=params)
+        resp.raise_for_status()
+        return resp.json()
+
+    def _post(self, path: str, payload: Optional[dict] = None) -> dict:
+        resp = self._client.post(path, json=payload)
+        resp.raise_for_status()
+        return resp.json()
+
+    # --- Registry ---
+
+    def register(self, agent_card: dict) -> dict:
+        """Register an agent in the registry."""
+        return self._post("/api/v1/agents", payload=agent_card)
+
+    def get_agent(self, agent_id: str) -> dict:
+        """Get agent details by DNA ID."""
+        return self._get(f"/api/v1/agents/{agent_id}")
+
+    def list_agents(self, limit: int = 20, offset: int = 0) -> dict:
+        """List registered agents."""
+        return self._get("/api/v1/agents", params={"limit": limit, "offset": offset})
+
+    # --- Discovery ---
+
+    def search(
+        self,
+        skill: Optional[str] = None,
+        language: Optional[str] = None,
+        max_price: Optional[float] = None,
+        min_reputation: Optional[float] = None,
+        verified: Optional[bool] = None,
+        protocol: Optional[str] = None,
+        tags: Optional[list[str]] = None,
+        limit: int = 10,
+        offset: int = 0,
+    ) -> dict:
+        """Search for agents by capability."""
+        params: dict[str, str | int | float] = {"limit": limit, "offset": offset}
+        if skill:
+            params["skill"] = skill
+        if language:
+            params["language"] = language
+        if max_price is not None:
+            params["max_price"] = max_price
+        if min_reputation is not None:
+            params["min_reputation"] = min_reputation
+        if verified is not None:
+            params["verified"] = str(verified).lower()
+        if protocol:
+            params["protocol"] = protocol
+        if tags:
+            params["tags"] = ",".join(tags)
+        return self._get("/api/v1/agents/search", params=params)
+
+    # --- Trust ---
+
+    def get_trust_score(self, agent_id: str) -> dict:
+        """Get the trust/reputation score for an agent."""
+        return self._get(f"/api/v1/agents/{agent_id}/trust")
+
+    def submit_review(self, agent_id: str, rating: int, comment: str, task_id: Optional[str] = None) -> dict:
+        """Submit a review for an agent."""
+        return self._post(
+            f"/api/v1/agents/{agent_id}/reviews",
+            payload={"rating": rating, "comment": comment, "task_id": task_id},
+        )
+
+    # --- Marketplace ---
+
+    def create_task(self, agent_id: str, task: dict) -> dict:
+        """Create a task for an agent (hire them)."""
+        return self._post(f"/api/v1/agents/{agent_id}/tasks", payload=task)
+
+    def get_task(self, task_id: str) -> dict:
+        """Get task status and result."""
+        return self._get(f"/api/v1/tasks/{task_id}")
+
+    # --- Heartbeat ---
+
+    def ping(self, agent_id: str) -> dict:
+        """Send a heartbeat ping for an agent."""
+        return self._post(f"/api/v1/agents/{agent_id}/heartbeat")
+
+    def close(self):
+        """Close the HTTP client."""
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

agentdna/discovery.py

@@ -0,0 +1,162 @@
+"""Agent discovery and search."""
+
+from typing import Optional
+
+from agentdna.client import AgentDNAClient
+from agentdna.models import Agent, AgentSearchResult, Capability, Pricing, TrustScore
+
+# Fields accepted by TrustScore dataclass (ignore extra keys from server)
+_TRUST_FIELDS = {"total", "task_completion", "response_quality",
+                 "latency_reliability", "uptime_score", "verification_bonus"}
+# Fields accepted by Pricing dataclass
+_PRICING_FIELDS = {"model", "amount", "currency", "free_tier"}
+
+
+def _parse_agent(data: dict) -> Agent:
+    """Parse API response into Agent model."""
+    capabilities = []
+    for cap in data.get("capabilities", []) or []:
+        if not cap:
+            continue
+        pricing = None
+        if cap.get("pricing"):
+            pricing_data = {k: v for k, v in cap["pricing"].items() if k in _PRICING_FIELDS}
+            pricing = Pricing(**pricing_data)
+        capabilities.append(
+            Capability(
+                skill=cap.get("skill", ""),
+                description=cap.get("description", ""),
+                inputs=cap.get("inputs", []),
+                output=cap.get("output", ""),
+                languages=cap.get("languages", []),
+                pricing=pricing,
+            )
+        )
+
+    trust = None
+    if data.get("trust_score"):
+        ts_data = {k: v for k, v in data["trust_score"].items() if k in _TRUST_FIELDS}
+        trust = TrustScore(**ts_data)
+    elif data.get("trust_total") is not None:
+        # Server returns trust fields with trust_ prefix (flat structure)
+        trust = TrustScore(
+            total=data.get("trust_total", 0),
+            task_completion=data.get("trust_task_completion", 0),
+            response_quality=data.get("trust_response_quality", 0),
+            latency_reliability=data.get("trust_latency_reliability", 0),
+            uptime_score=data.get("trust_uptime_score", 0),
+            verification_bonus=data.get("trust_verification_bonus", 0),
+        )
+    elif (
+        isinstance(data.get("total"), int)
+        and "task_completion" in data
+    ):
+        # Flat trust fields (e.g., direct trust endpoint response)
+        trust = TrustScore(
+            total=data.get("total", 0),
+            task_completion=data.get("task_completion", 0),
+            response_quality=data.get("response_quality", 0),
+            latency_reliability=data.get("latency_reliability", 0),
+            uptime_score=data.get("uptime_score", 0),
+            verification_bonus=data.get("verification_bonus", 0),
+        )
+
+    # Safe nested access — handles None values at any level
+    metadata = data.get("metadata") or {}
+    owner = data.get("owner") or {}
+
+    return Agent(
+        id=data.get("id", data.get("agent_id", "")),
+        name=data.get("name", ""),
+        version=data.get("version", ""),
+        description=data.get("description", ""),
+        protocol=data.get("protocol", ""),
+        endpoint=data.get("endpoint", ""),
+        capabilities=capabilities,
+        trust_score=trust,
+        tags=metadata.get("tags", []),
+        verified=data.get("verified", False),
+        owner_name=owner.get("name", ""),
+        repository=metadata.get("repository", ""),
+    )
+
+
+def find_agent(
+    skill: Optional[str] = None,
+    language: Optional[str] = None,
+    max_price: Optional[float] = None,
+    min_reputation: Optional[float] = None,
+    verified: Optional[bool] = None,
+    protocol: Optional[str] = None,
+    tags: Optional[list[str]] = None,
+    api_key: Optional[str] = None,
+) -> Optional[Agent]:
+    """
+    Find the best agent matching your criteria.
+
+    Returns the highest-reputation agent that matches all filters.
+
+    Example:
+        agent = find_agent(
+            skill="transcribe",
+            language="zh",
+            max_price=0.03,
+            min_reputation=4.5,
+            verified=True
+        )
+    """
+    results = search_agents(
+        skill=skill,
+        language=language,
+        max_price=max_price,
+        min_reputation=min_reputation,
+        verified=verified,
+        protocol=protocol,
+        tags=tags,
+        limit=1,
+        api_key=api_key,
+    )
+    return results.best()
+
+
+def search_agents(
+    skill: Optional[str] = None,
+    language: Optional[str] = None,
+    max_price: Optional[float] = None,
+    min_reputation: Optional[float] = None,
+    verified: Optional[bool] = None,
+    protocol: Optional[str] = None,
+    tags: Optional[list[str]] = None,
+    limit: int = 10,
+    offset: int = 0,
+    api_key: Optional[str] = None,
+) -> AgentSearchResult:
+    """
+    Search for agents by capability.
+
+    Returns a list of matching agents sorted by trust score.
+
+    Example:
+        results = search_agents(skill="code-review", language="en")
+        for agent in results.agents:
+            print(f"{agent.name}: {agent.trust_score.total}/100")
+    """
+    with AgentDNAClient(api_key=api_key or "") as client:
+        data = client.search(
+            skill=skill,
+            language=language,
+            max_price=max_price,
+            min_reputation=min_reputation,
+            verified=verified,
+            protocol=protocol,
+            tags=tags,
+            limit=limit,
+            offset=offset,
+        )
+
+    agents = [_parse_agent(a) for a in data.get("agents", [])]
+    return AgentSearchResult(
+        agents=agents,
+        total=data.get("total", len(agents)),
+        query=data.get("query", {}),
+    )