techtide-swarm 0.1.0__tar.gz

techtide_swarm-0.1.0/.gitignore

@@ -0,0 +1,64 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Virtual environments
+venv/
+.venv/
+
+# IDE / editor
+.cursor/hooks/state/
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Next.js build artifacts
+.ui_landin_sample/minimal/.next/
+.ui_landin_sample/minimal/node_modules/
+
+# Rust build
+packages/memvid-swarm-bridge/target/
+.repos and items/memvid-main/memvid-main/target/
+
+# Swarm runtime state (generated at runtime, not source)
+.swarm/topics/
+.swarm/telemetry.jsonl
+.swarm/MEMORY.md
+.swarm/*.mv2
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env files
+.env
+.env.local
+
+# Quarantined legacy files
+_quarantine/
+
+# Git worktrees
+.worktrees/
+
+# Package-local runtime (never commit)
+**/.swarm/
+
+# Local test / vendor junk never ship
+.hypothesis/
+**/.hypothesis/
+.repos and items/**/assets/
+.repos and items/**/.cursor/
+.repos and items/**/*.png
+.repos and items/**/*.jpg
+.repos and items/**/*.jpeg
+.repos and items/**/*.webp
+.repos and items/**/*.gif

techtide_swarm-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: techtide-swarm
+Version: 0.1.0
+Summary: TechTide Swarm 357 — layered orchestration, durable memory bridge, and observability hooks.
+Project-URL: Homepage, https://github.com/TechTideOhio/swarm-357
+Project-URL: Repository, https://github.com/TechTideOhio/swarm-357
+Project-URL: Documentation, https://github.com/TechTideOhio/swarm-357#readme
+Project-URL: Changelog, https://github.com/TechTideOhio/swarm-357/blob/main/CHANGELOG.md
+Project-URL: Bug Tracker, https://github.com/TechTideOhio/swarm-357/issues
+Author-email: TechTide AI <ai@techtide.ai>
+License: Apache-2.0
+Keywords: agents,ai,ai-agents,anthropic,claude,llm,multi-agent,orchestration,swarm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.10
+Requires-Dist: anthropic>=0.40
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.5
+Requires-Dist: pyyaml>=6
+Requires-Dist: rich>=13
+Requires-Dist: uvicorn[standard]>=0.30
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Provides-Extra: supabase
+Requires-Dist: supabase>=2.0; extra == 'supabase'
+Provides-Extra: web
+Requires-Dist: exa-py>=1.0; extra == 'web'
+Requires-Dist: firecrawl-py>=0.0.20; extra == 'web'
+Description-Content-Type: text/markdown
+
+# techtide-swarm
+
+Python package for **Swarm 357**: `Agent`, `Swarm`, `UltraPlan`, `MemoryManager` (flat `.swarm/` or Memvid `.mv2` via `memvid-swarm-bridge`), `BashSecurityGate`, and the `swarm` CLI.
+
+## Install (editable, from repo root)
+
+```bash
+cd packages/techtide-swarm
+pip install -e ".[dev]"
+```
+
+Or from the monorepo root:
+
+```bash
+pip install -e "packages/techtide-swarm[dev]"
+```
+
+Ensure `anthropic` can reach the API when using live `Agent.run` (set `ANTHROPIC_API_KEY`).
+
+## Memvid bridge
+
+Optional: build `packages/memvid-swarm-bridge` and set `MEMVID_SWARM_BRIDGE` to the binary path, or add it to `PATH`. See [docs/MEMVID_BRIDGE.md](../../docs/MEMVID_BRIDGE.md) (repo root).
+
+## CLI
+
+```bash
+swarm init
+swarm demo
+```
+
+Full developer context: [CLAUDE.md](../../CLAUDE.md) at the swarm357 repo root.

techtide_swarm-0.1.0/README.md

@@ -0,0 +1,31 @@
+# techtide-swarm
+
+Python package for **Swarm 357**: `Agent`, `Swarm`, `UltraPlan`, `MemoryManager` (flat `.swarm/` or Memvid `.mv2` via `memvid-swarm-bridge`), `BashSecurityGate`, and the `swarm` CLI.
+
+## Install (editable, from repo root)
+
+```bash
+cd packages/techtide-swarm
+pip install -e ".[dev]"
+```
+
+Or from the monorepo root:
+
+```bash
+pip install -e "packages/techtide-swarm[dev]"
+```
+
+Ensure `anthropic` can reach the API when using live `Agent.run` (set `ANTHROPIC_API_KEY`).
+
+## Memvid bridge
+
+Optional: build `packages/memvid-swarm-bridge` and set `MEMVID_SWARM_BRIDGE` to the binary path, or add it to `PATH`. See [docs/MEMVID_BRIDGE.md](../../docs/MEMVID_BRIDGE.md) (repo root).
+
+## CLI
+
+```bash
+swarm init
+swarm demo
+```
+
+Full developer context: [CLAUDE.md](../../CLAUDE.md) at the swarm357 repo root.

techtide_swarm-0.1.0/pyproject.toml

@@ -0,0 +1,97 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "techtide-swarm"
+version = "0.1.0"
+description = "TechTide Swarm 357 — layered orchestration, durable memory bridge, and observability hooks."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "TechTide AI", email = "ai@techtide.ai" }]
+keywords = ["claude", "ai", "agents", "swarm", "anthropic", "llm", "orchestration", "multi-agent", "ai-agents"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Application Frameworks",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+  "anthropic>=0.40",
+  "pydantic>=2.5",
+  "pyyaml>=6",
+  "httpx>=0.27",
+  "rich>=13",
+  "fastapi>=0.115",
+  "uvicorn[standard]>=0.30",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8",
+  "pytest-asyncio>=0.24",
+  "ruff>=0.8",
+  "mypy>=1.13",
+  "types-PyYAML>=6.0",
+  "build>=1.0",
+]
+web = [
+  "exa-py>=1.0",
+  "firecrawl-py>=0.0.20",
+]
+supabase = [
+  "supabase>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/TechTideOhio/swarm-357"
+Repository = "https://github.com/TechTideOhio/swarm-357"
+Documentation = "https://github.com/TechTideOhio/swarm-357#readme"
+Changelog = "https://github.com/TechTideOhio/swarm-357/blob/main/CHANGELOG.md"
+"Bug Tracker" = "https://github.com/TechTideOhio/swarm-357/issues"
+
+[project.scripts]
+swarm = "techtide_swarm.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/techtide_swarm"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/techtide_swarm", "README.md", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+# Explicit default rule set — keep CI stable across ruff minor releases (0.16+).
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["techtide_swarm"]
+
+# CLI is large and UI-heavy; keep strict typing on library code.
+[[tool.mypy.overrides]]
+module = "techtide_swarm.cli"
+ignore_errors = true
+
+# Optional external integrations that ship no type stubs. These are only
+# imported when the corresponding extras ([web], [supabase]) are installed,
+# so allow missing imports for them without weakening type checking elsewhere.
+[[tool.mypy.overrides]]
+module = ["supabase", "exa_py", "firecrawl"]
+ignore_missing_imports = true

techtide_swarm-0.1.0/src/techtide_swarm/__init__.py

@@ -0,0 +1,30 @@
+"""TechTide Swarm 357 — public API."""
+
+from techtide_swarm.agent import Agent, AgentConfig, AgentResult
+from techtide_swarm.bash_gate import BashSecurityGate
+from techtide_swarm.memory import MemoryManager
+from techtide_swarm.memvid_bridge import MemvidBridge, MemvidBridgeError, resolve_bridge_binary
+from techtide_swarm.persistence import SwarmStore
+from techtide_swarm.swarm import CostController, Swarm, SwarmExecutionResult
+from techtide_swarm.tools.registry import TOOLSET_MAP, ToolRegistry, registry
+from techtide_swarm.ultra_plan import UltraPlan, UltraPlanConfig
+
+__all__ = [
+    "Agent",
+    "AgentConfig",
+    "AgentResult",
+    "BashSecurityGate",
+    "CostController",
+    "MemvidBridge",
+    "MemvidBridgeError",
+    "MemoryManager",
+    "Swarm",
+    "SwarmExecutionResult",
+    "SwarmStore",
+    "TOOLSET_MAP",
+    "ToolRegistry",
+    "UltraPlan",
+    "UltraPlanConfig",
+    "registry",
+    "resolve_bridge_binary",
+]

techtide_swarm-0.1.0/src/techtide_swarm/agent.py

@@ -0,0 +1,224 @@
+"""Single-agent runner."""
+
+from __future__ import annotations
+
+import os
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from techtide_swarm.core.types import LayerType
+
+
+class AgentConfig(BaseModel):
+    """Configuration for one agent."""
+
+    name: str
+    layer: LayerType
+    role: str
+    soul: str = ""
+    tools: list[str] = Field(default_factory=list)
+    model: str = "sonnet"
+    budget_limit_usd: float = 1.0
+    max_turns: int = 10
+
+
+@dataclass
+class AgentResult:
+    """Outcome of agent.run."""
+
+    output: str
+    cost_usd: float
+    latency_ms: int
+    status: str
+    agent_name: str = ""
+    error: str | None = None
+
+
+class Agent:
+    """One Claude-powered agent."""
+
+    def __init__(self, config: AgentConfig) -> None:
+        self.config = config
+
+    def _load_system_prompt(self) -> str | None:
+        """Read the SOUL.md template and return the system prompt body (after YAML front-matter)."""
+        soul_path = self.config.soul
+        if not soul_path:
+            return None
+        path = Path(soul_path)
+        if not path.is_file():
+            # Resolve relative to repo root (two levels up from this package's src/)
+            pkg_src = Path(__file__).resolve().parent
+            candidates = [
+                pkg_src.parent.parent.parent.parent / soul_path,  # repo root
+                pkg_src.parent.parent.parent / soul_path,
+            ]
+            for candidate in candidates:
+                if candidate.is_file():
+                    path = candidate
+                    break
+            else:
+                return None
+        text = path.read_text(encoding="utf-8")
+        # Strip YAML front-matter delimited by ---
+        if text.startswith("---"):
+            parts = text.split("---", 2)
+            if len(parts) >= 3:
+                return parts[2].strip()
+        return text.strip()
+
+    async def run(self, task: str) -> AgentResult:
+        """Execute task via Anthropic Messages API when API key is set; else deterministic stub."""
+        from techtide_swarm.llm import create_async_client, model_id as resolve_model_id, resolve_api_key
+
+        api_key = resolve_api_key()
+        if not api_key:
+            return self._stub_result(task)
+
+        started = time.perf_counter()
+        try:
+            from techtide_swarm.tools import get_anthropic_tools, execute_tool
+
+            client = create_async_client()
+            resolved_model = resolve_model_id(self.config.model)
+            system_prompt = self._load_system_prompt()
+            
+            messages: list[dict[str, Any]] = [{"role": "user", "content": task}]
+            tools = get_anthropic_tools(self.config.tools)
+            
+            total_cost = 0.0
+            final_text = ""
+            budget = self.config.budget_limit_usd
+            
+            for turn in range(self.config.max_turns):
+                if total_cost >= budget:
+                    final_text = f"Budget limit reached (${budget:.2f}). Stopping."
+                    break
+
+                create_kwargs: dict[str, Any] = {
+                    "model": resolved_model,
+                    "max_tokens": 4096,
+                    "messages": messages,
+                }
+                if system_prompt:
+                    create_kwargs["system"] = system_prompt
+                if tools:
+                    create_kwargs["tools"] = tools
+
+                message = await client.messages.create(**create_kwargs)
+                total_cost += self._estimate_cost(message, resolved_model)
+
+                messages.append({"role": "assistant", "content": message.content})
+
+                if total_cost >= budget:
+                    final_text = self._extract_text(message) or (
+                        f"Budget limit reached (${budget:.2f}). Stopping."
+                    )
+                    break
+
+                tool_uses = [block for block in message.content if getattr(block, "type", None) == "tool_use"]
+
+                if not tool_uses:
+                    final_text = self._extract_text(message)
+                    break
+                
+                tool_results = []
+                for tool_use in tool_uses:
+                    result_text = execute_tool(tool_use.name, tool_use.input)
+                    tool_results.append({
+                        "type": "tool_result",
+                        "tool_use_id": tool_use.id,
+                        "content": result_text
+                    })
+                
+                messages.append({"role": "user", "content": tool_results})
+            else:
+                final_text = "Max turns reached without completion."
+
+            elapsed_ms = int((time.perf_counter() - started) * 1000)
+            
+            from techtide_swarm.telemetry import log_telemetry
+            log_telemetry("agent_run", {
+                "agent_name": self.config.name,
+                "layer": self.config.layer.value,
+                "cost_usd": total_cost,
+                "latency_ms": elapsed_ms,
+                "status": "success",
+            })
+            
+            return AgentResult(
+                agent_name=self.config.name,
+                output=final_text,
+                cost_usd=total_cost,
+                latency_ms=elapsed_ms,
+                status="success",
+            )
+        except Exception as exc:  # noqa: BLE001 — surface to CLI
+            elapsed_ms = int((time.perf_counter() - started) * 1000)
+
+            from techtide_swarm.telemetry import log_telemetry
+            log_telemetry("agent_run", {
+                "agent_name": self.config.name,
+                "layer": self.config.layer.value,
+                "cost_usd": 0.0,
+                "latency_ms": elapsed_ms,
+                "status": "error",
+                "error": str(exc),
+            })
+
+            return AgentResult(
+                agent_name=self.config.name,
+                output="",
+                cost_usd=0.0,
+                latency_ms=elapsed_ms,
+                status="error",
+                error=str(exc),
+            )
+
+    def _stub_result(self, task: str) -> AgentResult:
+        preview = task[:200].replace("\n", " ")
+        return AgentResult(
+            agent_name=self.config.name,
+            output=(
+                f"[stub] Agent {self.config.name} ({self.config.layer.value}) would process:\n"
+                f"{preview}"
+            ),
+            cost_usd=0.0,
+            latency_ms=0,
+            status="success",
+        )
+
+    @staticmethod
+    def _model_id(short: str) -> str:
+        from techtide_swarm.llm import model_id as resolve_model_id
+
+        return resolve_model_id(short)
+
+    @staticmethod
+    def _extract_text(message: Any) -> str:
+        parts: list[str] = []
+        for block in getattr(message, "content", []) or []:
+            btype = getattr(block, "type", None)
+            if btype == "text":
+                parts.append(getattr(block, "text", ""))
+        return "\n".join(parts) if parts else str(message)
+
+    @staticmethod
+    def _estimate_cost(message: Any, model_id: str) -> float:
+        usage = getattr(message, "usage", None)
+        if usage is None:
+            return 0.01
+        inp = float(getattr(usage, "input_tokens", 0) or 0)
+        out = float(getattr(usage, "output_tokens", 0) or 0)
+        # Approximate list pricing snapshot (Claude 4.x, 2026) — override with real billing later
+        if "opus" in model_id.lower():
+            rate_in, rate_out = 15.0 / 1e6, 75.0 / 1e6
+        elif "haiku" in model_id.lower():
+            rate_in, rate_out = 0.80 / 1e6, 4.0 / 1e6
+        else:  # sonnet
+            rate_in, rate_out = 3.0 / 1e6, 15.0 / 1e6
+        return inp * rate_in + out * rate_out

techtide_swarm-0.1.0/src/techtide_swarm/bash_gate.py

@@ -0,0 +1,44 @@
+"""23-point style bash command validation (subset implemented; extend as needed)."""
+
+from __future__ import annotations
+
+import re
+import shlex
+
+
+class BashSecurityGate:
+    """Validate shell commands before execution."""
+
+    _BLOCK_PATTERNS: tuple[tuple[re.Pattern[str], str], ...] = (
+        (re.compile(r"(?i)\brm\s+(-[rf]*\s*)*[/~]"), "recursive delete toward root or home"),
+        (re.compile(r"(?i)\bcurl\b.*\|\s*bash"), "curl pipe to bash"),
+        (re.compile(r"(?i)\bwget\b.*\|\s*(?:sh|bash)"), "wget pipe to shell"),
+        (re.compile(r"(?i)\b(?:sudo\s+)?chmod\s+777\b"), "dangerous chmod"),
+        (re.compile(r"(?i)\$[\w_]*(?:KEY|SECRET|TOKEN|PASSWORD)\b"), "references secret env var"),
+        (re.compile(r"(?i)\b(?:ANTHROPIC|OPENAI|AWS|GCP)_(?:API_)?KEY\b"), "API key literal in argv"),
+        (re.compile(r"(?i)>\s*/etc/"), "redirect to system config"),
+        (re.compile(r"(?i)\bmkfs\b"), "disk format"),
+        (re.compile(r"(?i)\bdd\s+if="), "raw disk write"),
+        (re.compile(r"(?i)\bpython[23]?\s+-c\s+.*(?:exec|eval|import\s+os)"), "python code exec with os access"),
+        (re.compile(r"(?i)\bsudo\s+(?:rm|mv|cp|chown)\b"), "elevated file operation"),
+        (re.compile(r"(?i)\bnc\s+-[el]"), "netcat listener"),
+        (re.compile(r"(?i)>\s*/dev/(?:sd|hd|nvme)"), "redirect to block device"),
+    )
+
+    @classmethod
+    def validate(cls, command: str) -> tuple[bool, str]:
+        """Return (safe, reason). Safe commands get reason ''."""
+        stripped = command.strip()
+        if not stripped:
+            return False, "empty command"
+        try:
+            parts = shlex.split(stripped)
+        except ValueError as exc:
+            return False, f"unparseable shell: {exc}"
+        if not parts:
+            return False, "empty command"
+        joined = " ".join(parts)
+        for pattern, reason in cls._BLOCK_PATTERNS:
+            if pattern.search(stripped) or pattern.search(joined):
+                return False, reason
+        return True, ""