antz-studio 0.1.0__py3-none-any.whl

antz/__init__.py

@@ -0,0 +1,29 @@
+# Antz Studio -- Colony SDK
+# Sovereign Agentic OS - antz.studio
+
+from antz.decorators import agent, tool, memory
+from antz.client import AntzClient
+from antz.config import AntzConfig
+from antz.hive_mode import HiveMode
+from antz.db_connector import db_connector
+from antz.privacy import add_gaussian_noise
+from antz.exceptions import (
+    AntzConnectionError,
+    ConstitutionViolationError,
+    AntzAuthError,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "agent",
+    "tool",
+    "memory",
+    "HiveMode",
+    "db_connector",
+    "add_gaussian_noise",
+    "AntzClient",
+    "AntzConfig",
+    "AntzConnectionError",
+    "ConstitutionViolationError",
+    "AntzAuthError",
+]

antz/cli.py

@@ -0,0 +1,545 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+import yaml
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+app     = typer.Typer(help="Ant'z Studio — Sovereign Agentic OS CLI", add_completion=False)
+console = Console()
+
+
+# ── antz login ────────────────────────────────────────────────────────────────
+
+@app.command()
+def login(
+    nest: str = typer.Option(..., "--nest", help="Nest URL (e.g. http://nest.local:8001)"),
+    api_key: str = typer.Option(..., "--api-key", help="Nest API key"),
+    mode: str = typer.Option("isolated", "--mode", help="isolated | shared | sovereign"),
+):
+    """Authenticate with a Nest and save credentials locally."""
+    from antz.config import AntzConfig
+    from antz.client import AntzClient
+
+    console.print(f"[dim]Connecting to Nest at {nest}...[/dim]")
+
+    try:
+        cfg    = AntzConfig(nest_url=nest, api_key=api_key, mode=mode)
+        client = AntzClient(cfg)
+        health = client.health()
+
+        AntzConfig.save_global(nest_url=nest, api_key=api_key, mode=mode)
+
+        console.print(Panel.fit(
+            f"[green]✓ Connected[/green]\n\n"
+            f"  Nest:    [cyan]{nest}[/cyan]\n"
+            f"  Mode:    [yellow]{mode}[/yellow]\n"
+            f"  Version: {health.get('version', 'unknown')}\n\n"
+            f"Credentials saved to [dim]~/.antz/config.yaml[/dim]",
+            title="Ant'z Studio",
+            border_style="green",
+        ))
+
+    except Exception as e:
+        console.print(f"[red]✗ Connection failed:[/red] {e}")
+        console.print("[dim]Hint: make sure the Nest is running and the API key is correct.[/dim]")
+        raise typer.Exit(1)
+
+
+# ── antz status ───────────────────────────────────────────────────────────────
+
+@app.command()
+def status():
+    """Check connection to the configured Nest."""
+    from antz.config import AntzConfig
+    from antz.client import AntzClient
+
+    try:
+        cfg    = AntzConfig.load()
+        client = AntzClient(cfg)
+        health = client.health()
+
+        table = Table(show_header=False, box=None, padding=(0, 2))
+        table.add_row("[dim]Nest URL[/dim]",  f"[cyan]{cfg.nest_url}[/cyan]")
+        table.add_row("[dim]Mode[/dim]",      f"[yellow]{cfg.mode}[/yellow]")
+        table.add_row("[dim]Status[/dim]",    "[green]● online[/green]")
+        table.add_row("[dim]Version[/dim]",   health.get("version", "unknown"))
+
+        console.print(Panel(table, title="Ant'z Nest Status", border_style="green"))
+
+    except Exception as e:
+        console.print(f"[red]✗ Cannot reach Nest:[/red] {e}")
+        console.print("[dim]Run: antz login --nest <url> --api-key <key>[/dim]")
+        raise typer.Exit(1)
+
+
+# ── antz init colony ──────────────────────────────────────────────────────────
+
+@app.command()
+def init(
+    resource: str = typer.Argument(..., help="Resource type: colony"),
+    name: str = typer.Argument(..., help="Colony name (e.g. financial-credit-analysis)"),
+    framework: str = typer.Option("langgraph", "--framework", "-f",
+                                   help="langgraph | crewai | mixed"),
+):
+    """Scaffold a new Colony with the chosen framework template."""
+    if resource != "colony":
+        console.print(f"[red]Unknown resource '{resource}'. Currently supported: colony[/red]")
+        raise typer.Exit(1)
+
+    target = Path.cwd() / f"colony-{name}"
+
+    if target.exists():
+        console.print(f"[red]✗ Directory '{target.name}' already exists.[/red]")
+        raise typer.Exit(1)
+
+    _scaffold_colony(name=name, framework=framework, target=target)
+
+    console.print(Panel.fit(
+        f"[green]✓ Colony scaffolded[/green]\n\n"
+        f"  Name:      [cyan]{name}[/cyan]\n"
+        f"  Framework: [yellow]{framework}[/yellow]\n"
+        f"  Directory: [dim]{target}[/dim]\n\n"
+        f"Next steps:\n"
+        f"  [dim]cd colony-{name}[/dim]\n"
+        f"  [dim]code .[/dim]                  # open in VSCode\n"
+        f"  [dim]antz run --demo[/dim]         # run the example agent",
+        title="Colony created",
+        border_style="cyan",
+    ))
+
+
+# ── antz run ──────────────────────────────────────────────────────────────────
+
+@app.command()
+def run(
+    input_file: Optional[Path] = typer.Option(None, "--input", "-i",
+                                               help="JSON input file for the agent"),
+    demo: bool = typer.Option(False, "--demo", help="Run the built-in demo agent"),
+    colony_dir: Optional[Path] = typer.Option(None, "--colony", "-c",
+                                               help="Colony directory (default: cwd)"),
+):
+    """Execute the Colony agent."""
+    cwd = colony_dir or Path.cwd()
+    cfg_file = cwd / "antz.config.yaml"
+
+    if not cfg_file.exists():
+        console.print(
+            "[red]✗ No antz.config.yaml found.[/red]\n"
+            "[dim]Run from inside a Colony directory, or use: antz init colony <name>[/dim]"
+        )
+        raise typer.Exit(1)
+
+    with open(cfg_file) as f:
+        colony_cfg = yaml.safe_load(f) or {}
+
+    colony_id  = colony_cfg.get("colony_id", "unknown")
+    entrypoint = colony_cfg.get("entrypoint", "agents/main.py")
+
+    console.print(f"[dim]Running Colony [cyan]{colony_id}[/cyan]...[/dim]")
+
+    if demo:
+        _run_demo(cwd, colony_cfg)
+        return
+
+    entry_path = cwd / entrypoint
+    if not entry_path.exists():
+        console.print(f"[red]✗ Entrypoint not found: {entry_path}[/red]")
+        raise typer.Exit(1)
+
+    cmd = [sys.executable, str(entry_path)]
+    if input_file:
+        cmd += ["--input", str(input_file)]
+
+    result = subprocess.run(cmd, cwd=str(cwd))
+    raise typer.Exit(result.returncode)
+
+
+# ── antz version ─────────────────────────────────────────────────────────────
+
+@app.command()
+def version():
+    """Show SDK version."""
+    from antz import __version__
+    console.print(f"antz-sdk [cyan]{__version__}[/cyan]")
+
+
+# ── Internal helpers ──────────────────────────────────────────────────────────
+
+def _scaffold_colony(name: str, framework: str, target: Path) -> None:
+    """Create Colony directory structure from template."""
+    target.mkdir(parents=True)
+
+    (target / "agents").mkdir()
+    (target / "tools").mkdir()
+    (target / "workflows").mkdir()
+    (target / "tests").mkdir()
+
+    # antz.config.yaml
+    config = {
+        "colony_id":  name,
+        "framework":  framework,
+        "entrypoint": "agents/main.py",
+        "nest_url":   "http://localhost:8001",
+        "mode":       "isolated",
+    }
+    with open(target / "antz.config.yaml", "w", encoding="utf-8") as f:
+        yaml.dump(config, f, default_flow_style=False)
+
+    # constitution.yaml
+    constitution = {
+        "agent_id": f"{name}-v1",
+        "version":  "1.0",
+        "allowed_tools": [],
+        "prohibited_actions": ["delete_record", "export_data", "modify_audit_log"],
+        "spend_limits": {"max_per_action_usd": 5.0, "max_per_day_usd": 500.0},
+        "data_policy": {
+            "can_send_outside_nest": False,
+            "can_log_pii": False,
+            "audit_all_tool_calls": True,
+        },
+    }
+    with open(target / "constitution.yaml", "w", encoding="utf-8") as f:
+        yaml.dump(constitution, f, default_flow_style=False)
+
+    # agents/main.py
+    agent_code = _agent_template(name=name, framework=framework)
+    with open(target / "agents" / "main.py", "w", encoding="utf-8") as f:
+        f.write(agent_code)
+
+    # README
+    with open(target / "README.md", "w", encoding="utf-8") as f:
+        f.write(_readme_template(name=name, framework=framework))
+
+
+def _agent_template(name: str, framework: str) -> str:
+    safe_name = name.replace("-", "_")
+
+    if framework == "langgraph":
+        return f'''# Colony: {name}
+# Framework: LangGraph
+# Ant'z SDK injects: observability, audit, constitution validation, memory
+
+from antz import agent, tool, memory
+from typing import TypedDict
+
+
+# ── State ─────────────────────────────────────────────────────────────────────
+
+class AgentState(TypedDict):
+    input: dict
+    result: dict
+    status: str
+
+
+# ── Tools ─────────────────────────────────────────────────────────────────────
+
+@tool("{safe_name}-lookup")
+def lookup_data(query: str) -> dict:
+    """
+    Replace with your actual tool logic.
+    Ant'z automatically logs this call and validates against constitution.
+    """
+    return {{"data": f"mock result for: {{query}}", "confidence": 0.9}}
+
+
+# ── Main agent ────────────────────────────────────────────────────────────────
+
+@agent("{safe_name}-v1")
+@memory(namespace="{safe_name}")
+def run_agent(input_data: dict, memory_context: list = None) -> dict:
+    """
+    Main agent entrypoint.
+    memory_context is auto-populated with relevant past runs from Hive.
+    Replace the logic below with your LangGraph workflow.
+    """
+    past    = memory_context or []
+    context = past[0]["content"] if past else "No prior context."
+
+    result = lookup_data(str(input_data))
+
+    return {{
+        "status":       "success",
+        "colony":       "{name}",
+        "result":       result,
+        "memory_hits":  len(past),
+        "context_used": context,
+    }}
+
+
+# ── Demo entrypoint ───────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    import json, sys
+
+    sample_input = {{"query": "demo run", "source": "antz-cli"}}
+
+    if "--input" in sys.argv:
+        idx = sys.argv.index("--input")
+        with open(sys.argv[idx + 1]) as f:
+            sample_input = json.load(f)
+
+    output = run_agent(sample_input)
+    print(json.dumps(output, indent=2))
+'''
+
+    elif framework == "crewai":
+        return f'''# Colony: {name}
+# Framework: CrewAI
+# Ant'z SDK injects: observability, audit, constitution validation, memory
+
+from antz import agent, tool, memory
+from crewai import Agent, Task, Crew
+
+
+# ── Tools ─────────────────────────────────────────────────────────────────────
+
+@tool("{safe_name}-lookup")
+def lookup_data(query: str) -> str:
+    """Replace with your actual tool logic."""
+    return f"mock result for: {{query}}"
+
+
+# ── Crew definition ───────────────────────────────────────────────────────────
+
+def build_crew():
+    analyst = Agent(
+        role="Data Analyst",
+        goal="Analyze input data and produce a structured report",
+        backstory="Expert analyst with deep domain knowledge",
+        verbose=False,
+    )
+    task = Task(
+        description="Analyze the provided data and return a structured summary.",
+        expected_output="A JSON-formatted analysis report",
+        agent=analyst,
+    )
+    return Crew(agents=[analyst], tasks=[task], verbose=False)
+
+
+# ── Main agent ────────────────────────────────────────────────────────────────
+
+@agent("{safe_name}-v1")
+@memory(namespace="{safe_name}")
+def run_agent(input_data: dict, memory_context: list = None) -> dict:
+    """
+    Main agent entrypoint.
+    memory_context is auto-populated with relevant past runs from Hive.
+    """
+    past   = memory_context or []
+    crew   = build_crew()
+    result = crew.kickoff(inputs=input_data)
+    return {{
+        "status":      "success",
+        "colony":      "{name}",
+        "result":      str(result),
+        "memory_hits": len(past),
+    }}
+
+
+# ── Demo entrypoint ───────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    import json, sys
+
+    sample_input = {{"query": "demo run", "source": "antz-cli"}}
+
+    if "--input" in sys.argv:
+        idx = sys.argv.index("--input")
+        with open(sys.argv[idx + 1]) as f:
+            sample_input = json.load(f)
+
+    output = run_agent(sample_input)
+    print(json.dumps(output, indent=2))
+'''
+
+    else:  # mixed
+        return f'''# Colony: {name}
+# Framework: Mixed (LangGraph + raw LiteLLM)
+# Ant'z SDK injects: observability, audit, constitution validation, memory
+
+from antz import agent, tool, memory
+import httpx
+import os
+
+LITELLM_URL = os.getenv("ANTZ_LITELLM_URL", "http://localhost:4000")
+
+
+# ── Tools ─────────────────────────────────────────────────────────────────────
+
+@tool("{safe_name}-llm-call")
+def call_llm(prompt: str) -> str:
+    """Direct LiteLLM call through the Nest — stays sovereign."""
+    r = httpx.post(
+        f"{{LITELLM_URL}}/chat/completions",
+        json={{
+            "model": "antz-default",
+            "messages": [{{"role": "user", "content": prompt}}],
+            "max_tokens": 512,
+        }},
+        timeout=30,
+    )
+    r.raise_for_status()
+    return r.json()["choices"][0]["message"]["content"]
+
+
+# ── Main agent ────────────────────────────────────────────────────────────────
+
+@agent("{safe_name}-v1")
+@memory(namespace="{safe_name}")
+def run_agent(input_data: dict, memory_context: list = None) -> dict:
+    """
+    Main agent with memory context from Hive.
+    memory_context is auto-populated with relevant past runs.
+    """
+    past        = memory_context or []
+    context_str = "\\n".join(str(m) for m in past[:3]) if past else "No prior context."
+
+    prompt = f"""
+Context from previous runs:
+{{context_str}}
+
+Current input: {{input_data}}
+
+Analyze and respond with a structured result.
+"""
+
+    response = call_llm(prompt)
+
+    return {{
+        "status":      "success",
+        "colony":      "{name}",
+        "result":      response,
+        "memory_hits": len(past),
+    }}
+
+
+# ── Demo entrypoint ───────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    import json, sys
+
+    sample_input = {{"query": "demo run", "source": "antz-cli"}}
+
+    if "--input" in sys.argv:
+        idx = sys.argv.index("--input")
+        with open(sys.argv[idx + 1]) as f:
+            sample_input = json.load(f)
+
+    output = run_agent(sample_input)
+    print(json.dumps(output, indent=2))
+'''
+
+
+def _readme_template(name: str, framework: str) -> str:
+    return f"""# Colony: {name}
+
+Framework: `{framework}`
+
+## Run
+
+```bash
+# Demo (no input required)
+antz run --demo
+
+# With input file
+antz run --input data/sample.json
+```
+
+## Structure
+
+```
+agents/main.py       # Main agent logic — edit this
+tools/               # Add your tools here
+workflows/           # Workflow definitions
+constitution.yaml    # Agent behavioral constraints
+antz.config.yaml     # Colony configuration
+```
+
+## Constitution
+
+Edit `constitution.yaml` to define what this agent can and cannot do.
+The Ant'z Hive validates every tool call against these rules at runtime.
+
+## Observability
+
+All executions are automatically traced. View them in the Nest Grafana dashboard.
+"""
+
+
+def _run_demo(cwd: Path, colony_cfg: dict) -> None:
+    """Run the demo mode — executes agents/main.py with sample data."""
+    entry = cwd / "agents" / "main.py"
+    if not entry.exists():
+        console.print("[red]✗ agents/main.py not found.[/red]")
+        raise typer.Exit(1)
+
+    console.print("[dim]Running demo agent...[/dim]\n")
+    result = subprocess.run([sys.executable, str(entry)], cwd=str(cwd))
+    raise typer.Exit(result.returncode)
+
+
+
+
+# -- antz nest ----------------------------------------------------------------
+
+@app.command("nest")
+def nest_cmd(
+    action: str = typer.Argument(..., help="status"),
+    tenant: str = typer.Option(..., "--tenant", "-t", help="Tenant ID"),
+    watch: bool = typer.Option(False, "--watch", "-w"),
+    api_key: str = typer.Option(None, "--api-key"),
+):
+    """Manage Nest provisioning and status."""
+    import httpx, os, time
+    cp_url = os.getenv("ANTZ_CONTROL_PLANE_URL", "https://control.antz.studio")
+    if not api_key:
+        api_key = typer.prompt("Control Plane API Key")
+    STATUS = {
+        "pending": "Aguardando...", "provisioning": "Iniciando...",
+        "creating_vm": "Criando VM...", "vm_created": "VM criada...",
+        "wireguard_ready": "WireGuard pronto...", "provisioning_nest": "Instalando Nest...",
+        "sending_email": "Enviando email...", "active": "Nest ativo!", "failed": "Falhou",
+    }
+    def get():
+        try:
+            r = httpx.get(f"{cp_url}/tenants/{tenant}", headers={"x-api-key": api_key}, timeout=10)
+            return r.json() if r.status_code == 200 else None
+        except Exception:
+            return None
+    data = get()
+    if not data:
+        console.print(f"[red]Tenant {tenant!r} nao encontrado.[/red]")
+        raise typer.Exit(1)
+    if not watch:
+        console.print(f"Tenant: [cyan]{tenant}[/cyan]")
+        console.print(f"Status: {STATUS.get(data.get('status','?'), data.get('status','?'))}")
+        if data.get("nest_url"):
+            console.print(f"URL: [green]{data['nest_url']}[/green]")
+        return
+    last = None
+    while True:
+        data = get()
+        if not data:
+            time.sleep(10); continue
+        s = data.get("status", "")
+        if s != last:
+            console.print(STATUS.get(s, s)); last = s
+        if s == "active":
+            url = data.get("nest_url", "")
+            console.print(f"[green]Nest ativo em {url}[/green]")
+            console.print(f"[dim]antz login --nest {url} --api-key SUA_CHAVE[/dim]")
+            raise typer.Exit(0)
+        if s == "failed":
+            console.print("[red]Falhou.[/red]"); raise typer.Exit(1)
+        time.sleep(15)
+
+
+if __name__ == "__main__":
+    app()

antz/client.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import httpx
+from typing import Any, Optional
+
+from antz.config import AntzConfig
+from antz.exceptions import AntzConnectionError, AntzAuthError
+
+
+class AntzClient:
+    """
+    Low-level HTTP client for Nest and Hive APIs.
+    Used internally by decorators — developers rarely call this directly.
+    """
+
+    def __init__(self, config: Optional[AntzConfig] = None):
+        self.config = config or AntzConfig.load()
+        self._headers = {
+            "Authorization": f"Bearer {self.config.api_key}",
+            "Content-Type": "application/json",
+            "X-Antz-Mode": self.config.mode,
+        }
+
+    # ── Nest endpoints ────────────────────────────────────────────────────────
+
+    def health(self) -> dict:
+        """Ping the Nest health endpoint."""
+        return self._get(f"{self.config.nest_url}/health")
+
+    def validate_constitution(self, agent_id: str, action: str, payload: dict) -> dict:
+        """
+        Ask the Nest constitution engine whether an action is permitted.
+        Returns: {"allowed": bool, "rule_id": str | None, "message": str}
+        """
+        return self._post(
+            f"{self.config.nest_url}/constitution/validate",
+            {"agent_id": agent_id, "action": action, "payload": payload},
+        )
+
+    def log_audit(self, event: dict) -> dict:
+        """Write an immutable audit event to the Nest append-only DB."""
+        return self._post(f"{self.config.nest_url}/audit/log", event)
+
+    # ── Hive endpoints ────────────────────────────────────────────────────────
+
+    def memory_store(self, namespace: str, agent_id: str, content: str, metadata: dict) -> dict:
+        base = self.config.hive_url or self.config.nest_url
+        return self._post(
+            f"{base}/memory/store",
+            {"namespace": namespace, "agent_id": agent_id,
+             "content": content, "metadata": metadata},
+        )
+
+    def memory_search(self, namespace: str, query: str, top_k: int = 5) -> list[dict]:
+        base = self.config.hive_url or self.config.nest_url
+        result = self._get(
+            f"{base}/memory/search",
+            params={"namespace": namespace, "query": query, "top_k": top_k},
+        )
+        return result.get("results", [])
+
+    # ── Internal helpers ──────────────────────────────────────────────────────
+
+    def _get(self, url: str, params: Optional[dict] = None) -> Any:
+        try:
+            r = httpx.get(url, headers=self._headers, params=params, timeout=10)
+            self._raise_for_status(r)
+            return r.json()
+        except httpx.ConnectError as e:
+            raise AntzConnectionError(f"Cannot reach Nest at {self.config.nest_url}: {e}") from e
+
+    def _post(self, url: str, body: dict) -> Any:
+        try:
+            r = httpx.post(url, headers=self._headers, json=body, timeout=15)
+            self._raise_for_status(r)
+            return r.json()
+        except httpx.ConnectError as e:
+            raise AntzConnectionError(f"Cannot reach Nest at {self.config.nest_url}: {e}") from e
+
+    def _raise_for_status(self, r: httpx.Response) -> None:
+        if r.status_code == 401:
+            raise AntzAuthError("Invalid API key. Run: antz login --nest <url> --api-key <key>")
+        if r.status_code >= 400:
+            raise AntzConnectionError(f"Nest returned {r.status_code}: {r.text}")
+
+    def sync_to_hive_central(self, namespace: str) -> dict:
+        """Trigger sync of anonymized vectors to Hive Central."""
+        return self._post(
+            f"{self.config.nest_url}/sync/push",
+            {"namespace": namespace, "top_k": 100},
+        )

antz/config.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+import yaml
+from pydantic import BaseModel, field_validator
+
+
+# ── Config file locations ─────────────────────────────────────────────────────
+GLOBAL_CONFIG_PATH = Path.home() / ".antz" / "config.yaml"
+LOCAL_CONFIG_NAME  = "antz.config.yaml"
+
+
+class AntzConfig(BaseModel):
+    """
+    Resolved configuration for the SDK.
+    Priority: env vars > local antz.config.yaml > ~/.antz/config.yaml
+    """
+    nest_url:   str
+    api_key:    str
+    colony_id:  Optional[str] = None
+    mode:       str = "isolated"   # isolated | shared | sovereign
+    hive_url:   Optional[str] = None
+
+    @field_validator("mode")
+    @classmethod
+    def validate_mode(cls, v: str) -> str:
+        allowed = {"isolated", "shared", "sovereign"}
+        if v not in allowed:
+            raise ValueError(f"mode must be one of {allowed}, got '{v}'")
+        return v
+
+    @field_validator("nest_url")
+    @classmethod
+    def strip_trailing_slash(cls, v: str) -> str:
+        return v.rstrip("/")
+
+    @classmethod
+    def load(cls, colony_dir: Optional[Path] = None) -> "AntzConfig":
+        """
+        Load config in priority order:
+        1. Environment variables
+        2. Local antz.config.yaml (in colony_dir or cwd)
+        3. Global ~/.antz/config.yaml
+        """
+        data: dict = {}
+
+        # 3. Global config (lowest priority)
+        if GLOBAL_CONFIG_PATH.exists():
+            data.update(_read_yaml(GLOBAL_CONFIG_PATH))
+
+        # 2. Local colony config
+        search_dir = colony_dir or Path.cwd()
+        local_cfg = search_dir / LOCAL_CONFIG_NAME
+        if local_cfg.exists():
+            data.update(_read_yaml(local_cfg))
+
+        # 1. Environment variables (highest priority)
+        if nest_url := os.getenv("ANTZ_NEST_URL"):
+            data["nest_url"] = nest_url
+        if api_key := os.getenv("ANTZ_API_KEY"):
+            data["api_key"] = api_key
+        if mode := os.getenv("ANTZ_MODE"):
+            data["mode"] = mode
+        if hive_url := os.getenv("ANTZ_HIVE_URL"):
+            data["hive_url"] = hive_url
+
+        if not data.get("nest_url") or not data.get("api_key"):
+            raise ValueError(
+                "Missing Ant'z credentials.\n"
+                "Run: antz login --nest <url> --api-key <key>\n"
+                "Or set ANTZ_NEST_URL and ANTZ_API_KEY environment variables."
+            )
+
+        return cls(**data)
+
+    @classmethod
+    def save_global(cls, nest_url: str, api_key: str, mode: str = "isolated") -> None:
+        """Persist credentials to ~/.antz/config.yaml (used by `antz login`)."""
+        GLOBAL_CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+        payload = {"nest_url": nest_url, "api_key": api_key, "mode": mode}
+        with open(GLOBAL_CONFIG_PATH, "w") as f:
+            yaml.dump(payload, f, default_flow_style=False)
+
+
+def _read_yaml(path: Path) -> dict:
+    with open(path) as f:
+        content = f.read()
+    # Resolve ${VAR} patterns
+    import re
+    def replace_env(match):
+        var = match.group(1)
+        return os.getenv(var, match.group(0))
+    content = re.sub(r'\$\{([^}]+)\}', replace_env, content)
+    return yaml.safe_load(content) or {}

antz/db_connector.py

@@ -0,0 +1,35 @@
+import os
+import httpx
+from typing import Any
+
+
+class DBConnector:
+    def __init__(self, name: str, nest_url: str, api_key: str):
+        self.name = name
+        self.nest_url = nest_url
+        self.api_key = api_key
+        self._engine = None
+
+    def _get_connection_url(self) -> str:
+        r = httpx.get(
+            f"{self.nest_url}/vault/db/{self.name}",
+            headers={"Authorization": f"Bearer {self.api_key}"},
+            timeout=10,
+        )
+        r.raise_for_status()
+        return r.json()["url"]
+
+    def execute(self, sql: str, params: list = None) -> list:
+        import sqlalchemy
+        if not self._engine:
+            url = self._get_connection_url()
+            self._engine = sqlalchemy.create_engine(url)
+        with self._engine.connect() as conn:
+            result = conn.execute(sqlalchemy.text(sql), params or {})
+            return [dict(row) for row in result]
+
+
+def db_connector(name: str) -> DBConnector:
+    from antz.config import AntzConfig
+    cfg = AntzConfig.load()
+    return DBConnector(name=name, nest_url=cfg.nest_url, api_key=cfg.api_key)

antz/decorators.py

@@ -0,0 +1,250 @@
+from __future__ import annotations
+
+import functools
+import time
+import traceback
+import uuid
+from typing import Any, Callable, Optional
+
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+
+from antz.exceptions import ConstitutionViolationError
+from antz.hive_mode import HiveMode
+from antz.privacy import add_gaussian_noise
+
+# -- Lazy OTel tracer ----------------------------------------------------------
+_tracer: Optional[trace.Tracer] = None
+
+
+def _get_tracer() -> trace.Tracer:
+    global _tracer
+    if _tracer is None:
+        _tracer = trace.get_tracer("antz.sdk", "0.1.0")
+    return _tracer
+
+
+def _setup_otel_if_needed(nest_url: str, api_key: str = None) -> None:
+    provider = TracerProvider()
+    headers = {}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    exporter = OTLPSpanExporter(
+        endpoint=f"{nest_url}/v1/traces",
+        headers=headers,
+    )
+    provider.add_span_processor(BatchSpanProcessor(exporter))
+    trace.set_tracer_provider(provider)
+
+
+# -- @agent --------------------------------------------------------------------
+
+def agent(agent_id: str, constitution: Optional[str] = None):
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs) -> Any:
+            from antz.config import AntzConfig
+            from antz.client import AntzClient
+
+            run_id   = str(uuid.uuid4())
+            start_ts = time.time()
+
+            try:
+                cfg    = AntzConfig.load()
+                client = AntzClient(cfg)
+                _setup_otel_if_needed(cfg.nest_url, cfg.api_key)
+            except Exception:
+                return func(*args, **kwargs)
+
+            tracer = _get_tracer()
+
+            with tracer.start_as_current_span(f"agent.{agent_id}") as span:
+                span.set_attribute("antz.agent_id", agent_id)
+                span.set_attribute("antz.run_id",   run_id)
+                span.set_attribute("antz.mode",     cfg.mode)
+
+                try:
+                    validation = client.validate_constitution(
+                        agent_id=agent_id,
+                        action=func.__name__,
+                        payload={"args_count": len(args), "kwargs": list(kwargs.keys())},
+                    )
+                    if not validation.get("allowed", True):
+                        raise ConstitutionViolationError(
+                            rule_id=validation.get("rule_id", "unknown"),
+                            action=func.__name__,
+                            message=validation.get("message", "Action blocked by constitution"),
+                        )
+                except ConstitutionViolationError:
+                    raise
+                except Exception:
+                    span.set_attribute("antz.constitution_check", "skipped")
+
+                status = "success"
+                result = None
+                try:
+                    result = func(*args, **kwargs)
+                    span.set_attribute("antz.status", "success")
+                except Exception as e:
+                    status = "failure"
+                    span.set_attribute("antz.status", "failure")
+                    span.set_attribute("antz.error",  str(e))
+                    span.record_exception(e)
+                    raise
+                finally:
+                    latency_ms = int((time.time() - start_ts) * 1000)
+                    span.set_attribute("antz.latency_ms", latency_ms)
+                    try:
+                        client.log_audit({
+                            "event_id":    run_id,
+                            "agent_id":    agent_id,
+                            "action_type": "agent_execution",
+                            "tool_called": func.__name__,
+                            "status":      status,
+                            "latency_ms":  latency_ms,
+                        })
+                    except Exception:
+                        pass
+
+                return result
+
+        wrapper._antz_agent_id = agent_id
+        return wrapper
+    return decorator
+
+
+# -- @tool ---------------------------------------------------------------------
+
+def tool(tool_id: str):
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs) -> Any:
+            from antz.config import AntzConfig
+            from antz.client import AntzClient
+
+            start_ts = time.time()
+
+            try:
+                cfg    = AntzConfig.load()
+                client = AntzClient(cfg)
+            except Exception:
+                return func(*args, **kwargs)
+
+            tracer = _get_tracer()
+
+            with tracer.start_as_current_span(f"tool.{tool_id}") as span:
+                span.set_attribute("antz.tool_id",   tool_id)
+                span.set_attribute("antz.pii_check", "pending_redaction")
+
+                try:
+                    validation = client.validate_constitution(
+                        agent_id="__tool__",
+                        action=tool_id,
+                        payload={},
+                    )
+                    if not validation.get("allowed", True):
+                        raise ConstitutionViolationError(
+                            rule_id=validation.get("rule_id", "unknown"),
+                            action=tool_id,
+                            message=validation.get("message", f"Tool '{tool_id}' blocked"),
+                        )
+                except ConstitutionViolationError:
+                    raise
+                except Exception:
+                    span.set_attribute("antz.constitution_check", "skipped")
+
+                status = "success"
+                try:
+                    result = func(*args, **kwargs)
+                    span.set_attribute("antz.status", "success")
+                    return result
+                except Exception as e:
+                    status = "failure"
+                    span.set_attribute("antz.status", "failure")
+                    span.record_exception(e)
+                    raise
+                finally:
+                    latency_ms = int((time.time() - start_ts) * 1000)
+                    span.set_attribute("antz.latency_ms", latency_ms)
+                    try:
+                        client.log_audit({
+                            "agent_id":    "__tool__",
+                            "action_type": "tool_call",
+                            "tool_called": tool_id,
+                            "status":      status,
+                            "latency_ms":  latency_ms,
+                        })
+                    except Exception:
+                        pass
+
+        wrapper._antz_tool_id = tool_id
+        return wrapper
+    return decorator
+
+
+# -- @memory -------------------------------------------------------------------
+
+def memory(namespace: str, hive: HiveMode = HiveMode.ISOLATED):
+    """
+    Decorator that wraps a function with Hive semantic memory.
+
+    hive=HiveMode.ISOLATED   ? default, zero leaves Nest
+    hive=HiveMode.SHARED     ? anon vectors sent to Hive Central
+    hive=HiveMode.SOVEREIGN  ? air-gapped, OTel disabled
+    """
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs) -> Any:
+            from antz.config import AntzConfig
+            from antz.client import AntzClient
+
+            # SOVEREIGN: skip all telemetry
+            if hive == HiveMode.SOVEREIGN:
+                kwargs.setdefault("memory_context", [])
+                return func(*args, **kwargs)
+
+            try:
+                cfg    = AntzConfig.load()
+                client = AntzClient(cfg)
+
+                query = " ".join(str(a) for a in args) + " ".join(
+                    f"{k}={v}" for k, v in kwargs.items()
+                )
+
+                memories = client.memory_search(
+                    namespace=namespace,
+                    query=query,
+                    top_k=5,
+                )
+                kwargs["memory_context"] = memories
+            except Exception:
+                kwargs.setdefault("memory_context", [])
+
+            result = func(*args, **kwargs)
+
+            # Store result in Hive memory
+            try:
+                client.memory_store(
+                    namespace=namespace,
+                    agent_id=func.__name__,
+                    content=str(result),
+                    metadata={"function": func.__name__, "hive_mode": hive.value},
+                )
+            except Exception as e:
+                print(f"[memory] store failed: {e}")
+
+            # SHARED: sync anonymized vectors to Hive Central
+            if hive == HiveMode.SHARED:
+                try:
+                    client.sync_to_hive_central(namespace=namespace)
+                except Exception as e:
+                    print(f"[memory] sync to Hive Central failed: {e}")
+
+            return result
+
+        wrapper._antz_memory_namespace = namespace
+        wrapper._antz_hive_mode = hive
+        return wrapper
+    return decorator

antz/exceptions.py

@@ -0,0 +1,35 @@
+class AntzError(Exception):
+    """Base exception for all Ant'z SDK errors."""
+    pass
+
+
+class AntzConnectionError(AntzError):
+    """Cannot reach the Nest endpoint."""
+    pass
+
+
+class AntzAuthError(AntzError):
+    """Invalid or missing API key."""
+    pass
+
+
+class ConstitutionViolationError(AntzError):
+    """
+    Raised when an agent action violates the Agentic Constitution.
+
+    Attributes:
+        rule_id: The constitution constraint that was violated.
+        action:  The action that triggered the violation.
+        message: Human-readable explanation.
+    """
+    def __init__(self, rule_id: str, action: str, message: str):
+        self.rule_id = rule_id
+        self.action = action
+        super().__init__(
+            f"[Constitution violation] rule='{rule_id}' action='{action}' — {message}"
+        )
+
+
+class ColonyNotFoundError(AntzError):
+    """Colony directory or config not found."""
+    pass

antz/hive_mode.py

@@ -0,0 +1,6 @@
+from enum import Enum
+
+class HiveMode(Enum):
+    ISOLATED = 'isolated'
+    SHARED = 'shared'
+    SOVEREIGN = 'sovereign'

antz/privacy.py

@@ -0,0 +1,24 @@
+import random
+import math
+
+
+def add_gaussian_noise(vector: list, epsilon: float = 1.0, sensitivity: float = 1.0) -> list:
+    """
+    Aplica differential privacy com ruido gaussiano.
+    Epsilon menor = mais privacidade, mais ruido.
+    Epsilon maior = menos privacidade, menos ruido.
+    """
+    sigma = sensitivity / epsilon
+    return [v + random.gauss(0, sigma) for v in vector]
+
+
+def privacy_budget(epsilon: float) -> str:
+    """Retorna descricao do nivel de privacidade."""
+    if epsilon <= 0.1:
+        return "very_high"
+    elif epsilon <= 1.0:
+        return "high"
+    elif epsilon <= 5.0:
+        return "medium"
+    else:
+        return "low"

antz_studio-0.1.0.dist-info/METADATA

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: antz-studio
+Version: 0.1.0
+Summary: Antz Studio -- Sovereign Agentic OS
+Author-email: Antz Studio <gabriel@antz.studio>
+License: AGPL-3.0
+Project-URL: Homepage, https://antz.studio
+Project-URL: Repository, https://github.com/Gabbsx7/antz-studio-aos
+Keywords: agents,sovereign-ai,agentic-os,llm,observability,nest,colony,hive
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: typer>=0.12
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: opentelemetry-api>=1.24
+Requires-Dist: opentelemetry-sdk>=1.24
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.24
+Requires-Dist: rich>=13.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: sqlalchemy>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-mock>=3.12; extra == "dev"
+Provides-Extra: cloud
+Requires-Dist: azure-mgmt-compute>=30.0.0; extra == "cloud"
+Requires-Dist: azure-mgmt-network>=25.0.0; extra == "cloud"
+Requires-Dist: azure-mgmt-resource>=23.0.0; extra == "cloud"
+Requires-Dist: azure-identity>=1.15.0; extra == "cloud"

antz_studio-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+antz/__init__.py,sha256=w8gFukkSXtdymQDoZnTcjuUkzUnCCMVmqoMwHGZ1Kjg,700
+antz/cli.py,sha256=t52PEQgW8l8GrN9UbvDfx0UuOV133dKuyg9cAjOI6UI,19972
+antz/client.py,sha256=eQlEjN96a0t1dWVM-r0MPfLX9t55NCvuaLzh7HvPEEo,4055
+antz/config.py,sha256=O0hT0GAlNI65DLSglj4Xo7aKpXvHx1MLgxPrgLl8xHI,3343
+antz/db_connector.py,sha256=c_NDoO_sKGHdNHEl1s89sYMQ-fOdoCvNtAhFpFTGZXo,1136
+antz/decorators.py,sha256=Ido52tjLKsfM6ZMH5Tksbn3CMptxBo5Qf2Ltps503Zk,9448
+antz/exceptions.py,sha256=6yUeNySc3rb8vUPkuiaqJvBrctaJSis1Ev0tZdTycfA,921
+antz/hive_mode.py,sha256=g97M7ZUnAyqgXYtTRwCNu5Ib-HKtQfUQ6folDThAkO8,127
+antz/privacy.py,sha256=hrea2Nd0A1cYKITASBh2P_lPrH9FydTsIHC9BterA6g,682
+antz_studio-0.1.0.dist-info/METADATA,sha256=TUuBk7nYJOKlLX6XUivxx7e3SlIA0AGSG-i3VAdDT5c,1420
+antz_studio-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+antz_studio-0.1.0.dist-info/entry_points.txt,sha256=v_JAzkfl2RdkZRZGpoHubSBPCtOWpTKXrpCUq3yIH2k,38
+antz_studio-0.1.0.dist-info/top_level.txt,sha256=JFEP9Nyk3w07ieuche5had6-CjcBbKJQx0HacgMTiV8,5
+antz_studio-0.1.0.dist-info/RECORD,,

antz_studio-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

antz_studio-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+antz = antz.cli:app

antz_studio-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+antz