apsimo 1.3.0__py3-none-any.whl

apsimo/reasoning/native_tools/web_search.py

@@ -0,0 +1,49 @@
+"""Web search native tool."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict
+
+logger = logging.getLogger(__name__)
+
+
+class WebSearchTool:
+    """Web search via Colony's SearchOrchestrator."""
+
+    def __init__(self, search_orchestrator=None):
+        self._orchestrator = search_orchestrator
+
+    @property
+    def name(self) -> str:
+        return "web_search"
+
+    @property
+    def schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "query": {"type": "string", "description": "Search query"},
+                "max_results": {"type": "integer", "description": "Max results (default 5)", "default": 5},
+            },
+            "required": ["query"],
+        }
+
+    async def execute(self, args: Dict[str, Any]) -> Dict[str, Any]:
+        if not self._orchestrator or not self._orchestrator.has_providers:
+            return {"error": True, "message": "Web search not configured"}
+
+        query = args.get("query", "")
+        max_results = args.get("max_results", 5)
+
+        try:
+            results = await self._orchestrator.search(query, max_results)
+            return {
+                "results": [
+                    {"title": r.title, "url": r.url, "snippet": r.snippet, "source": r.source}
+                    for r in results
+                ],
+                "count": len(results),
+            }
+        except Exception as e:
+            return {"error": True, "message": str(e)}

apsimo/reasoning/tool_policy.py

@@ -0,0 +1,182 @@
+"""Typed authorization policy for sidecar-resident reasoning tools.
+
+Model tool definitions are an ergonomics hint, not an enforcement boundary: a
+model (or a direct API caller) can still name a tool that was not advertised.
+This module gives every execution path the same small, conservative effect
+classification and actor policy.  Unknown and dynamically supplied tools are
+mutating until explicitly classified.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Mapping
+
+
+class ToolEffect(str, Enum):
+    """The authority needed to execute a tool."""
+
+    PUBLIC_READ = "public_read"
+    PRIVATE_READ = "private_read"
+    MUTATION = "mutation"
+
+
+@dataclass(frozen=True)
+class ToolActorPolicy:
+    """Server-derived capabilities for one reasoning turn or direct call.
+
+    ``None`` remains the compatibility representation for trusted in-process
+    callers. HTTP handlers must always supply a concrete policy while P8 is
+    attached; request-body identities never populate these fields.
+    """
+
+    principal_id: str
+    viewer_person_id: str
+    allow_private_read: bool = False
+    allow_mutation: bool = False
+
+
+# Pure/general information tools that do not expose Colony's private stores.
+_PUBLIC_READ_TOOLS = frozenset({
+    "calculate",
+    "web_search",
+})
+
+
+# Tools that can expose owner, contact, repository, memory, or self-state.
+# They are read-only, but are intentionally not guest-callable because most
+# legacy handlers do not yet seal selectors in their argument dictionaries.
+_PRIVATE_READ_TOOLS = frozenset({
+    "action_journal",
+    "belief_conflicts",
+    "colony_discover_connections",
+    "colony_get_briefing",
+    "colony_get_relationship",
+    "colony_list_boundaries",
+    "colony_list_goals",
+    "colony_memory_search",
+    "colony_query_entities",
+    "colony_recent_boundary_blocks",
+    "list_directory",
+    "list_projects",
+    "pending_contact_proposals",
+    "project_status",
+    "read_file",
+    "recall_skills",
+    "relationship_brief",
+    "repo_list_files",
+    "repo_read_file",
+    "repo_search",
+    "sandbox_status",
+    "self_status",
+})
+
+
+# Known state-changing tools. Unknown/dynamic tools also default to mutation.
+_MUTATION_TOOLS = frozenset({
+    "abandon_project",
+    "colony_flag_boundary_concern",
+    "colony_initiative_feedback",
+    "colony_record_insight",
+    "colony_start_research",
+    "colony_task_complete",
+    "colony_task_dismiss",
+    "colony_task_snooze",
+    "create_project",
+    "link_contact",
+    "merge_contacts",
+    "sandbox_run",
+    "write_file",
+})
+
+
+def classify_tool(name: str) -> ToolEffect:
+    """Return the tool's conservative effect class.
+
+    The explicit mutation set documents current first-party tools.  The final
+    branch is deliberately mutation: newly graduated/toolsmith tools cannot
+    silently inherit read authority merely because they are new.
+    """
+
+    normalized = str(name or "").strip()
+    if normalized in _PUBLIC_READ_TOOLS:
+        return ToolEffect.PUBLIC_READ
+    if normalized in _PRIVATE_READ_TOOLS:
+        return ToolEffect.PRIVATE_READ
+    if normalized in _MUTATION_TOOLS:
+        return ToolEffect.MUTATION
+    return ToolEffect.MUTATION
+
+
+def actor_allows_tool(
+    name: str,
+    actor: ToolActorPolicy | None,
+) -> bool:
+    """Whether actor capabilities permit this tool before boundary checks."""
+
+    return actor_allows_effect(classify_tool(name), actor)
+
+
+def actor_allows_effect(
+    effect: ToolEffect,
+    actor: ToolActorPolicy | None,
+) -> bool:
+    """Whether actor capabilities permit an already-resolved tool effect.
+
+    Callers with handler provenance must use this form. In particular, every
+    dynamic handler resolves to ``MUTATION`` even if its chosen name resembles
+    a shipped public or private read.
+    """
+
+    if actor is None:  # trusted in-process compatibility caller
+        return True
+    if effect is ToolEffect.PUBLIC_READ:
+        return True
+    if effect is ToolEffect.PRIVATE_READ:
+        return actor.allow_private_read
+    return actor.allow_mutation
+
+
+def filter_tools_for_actor(
+    names: list[str] | tuple[str, ...] | set[str] | frozenset[str],
+    actor: ToolActorPolicy | None,
+) -> list[str]:
+    """Preserve caller order while removing actor-inaccessible tool names."""
+
+    return [name for name in names if actor_allows_tool(name, actor)]
+
+
+def action_target(arguments: Mapping[str, Any]) -> str:
+    """Extract a useful human/resource subject for DirectiveGuard matching."""
+
+    for key in (
+        "target",
+        "target_path",
+        "path",
+        "repo",
+        "url",
+        "endpoint",
+        "who",
+        "contact_id",
+        "person_id",
+        "entity_id",
+        "topic",
+        "query",
+        "purpose",
+    ):
+        value = arguments.get(key)
+        if isinstance(value, (str, int, float)) and str(value).strip():
+            return str(value).strip()
+    return ""
+
+
+__all__ = [
+    "ToolActorPolicy",
+    "ToolEffect",
+    "action_target",
+    "actor_allows_effect",
+    "actor_allows_tool",
+    "classify_tool",
+    "filter_tools_for_actor",
+]

apsimo/redact/__init__.py

@@ -0,0 +1,176 @@
+"""Regex-based secret redaction for logs and tool output.
+
+Applies pattern matching to mask API keys, tokens, and credentials
+before they reach log files, verbose output, or gateway logs.
+
+Short tokens (< 18 chars) are fully masked. Longer tokens preserve
+the first 6 and last 4 characters for debuggability.
+"""
+
+import logging
+import os
+import re
+
+logger = logging.getLogger(__name__)
+
+# Known API key prefixes -- match the prefix + contiguous token chars
+_PREFIX_PATTERNS = [
+    r"sk-[A-Za-z0-9_-]{10,}",           # OpenAI / OpenRouter / Anthropic (sk-ant-*)
+    r"ghp_[A-Za-z0-9]{10,}",            # GitHub PAT (classic)
+    r"github_pat_[A-Za-z0-9_]{10,}",    # GitHub PAT (fine-grained)
+    r"xox[baprs]-[A-Za-z0-9-]{10,}",    # Slack tokens
+    r"AIza[A-Za-z0-9_-]{30,}",          # Google API keys
+    r"pplx-[A-Za-z0-9]{10,}",           # Perplexity
+    r"fal_[A-Za-z0-9_-]{10,}",          # Fal.ai
+    r"fc-[A-Za-z0-9]{10,}",             # Firecrawl
+    r"bb_live_[A-Za-z0-9_-]{10,}",      # BrowserBase
+    r"gAAAA[A-Za-z0-9_=-]{20,}",        # Codex encrypted tokens
+    r"AKIA[A-Z0-9]{16}",                # AWS Access Key ID
+    r"sk_live_[A-Za-z0-9]{10,}",        # Stripe secret key (live)
+    r"sk_test_[A-Za-z0-9]{10,}",        # Stripe secret key (test)
+    r"rk_live_[A-Za-z0-9]{10,}",        # Stripe restricted key
+    r"SG\.[A-Za-z0-9_-]{10,}",          # SendGrid API key
+    r"hf_[A-Za-z0-9]{10,}",             # HuggingFace token
+    r"r8_[A-Za-z0-9]{10,}",             # Replicate API token
+    r"npm_[A-Za-z0-9]{10,}",            # npm access token
+    r"pypi-[A-Za-z0-9_-]{10,}",         # PyPI API token
+    r"dop_v1_[A-Za-z0-9]{10,}",         # DigitalOcean PAT
+    r"doo_v1_[A-Za-z0-9]{10,}",         # DigitalOcean OAuth
+    r"am_[A-Za-z0-9_-]{10,}",           # AgentMail API key
+    r"sk_[A-Za-z0-9_]{10,}",            # ElevenLabs TTS key (sk_ underscore, not sk- dash)
+    r"tvly-[A-Za-z0-9]{10,}",           # Tavily search API key
+    r"exa_[A-Za-z0-9]{10,}",            # Exa search API key
+]
+
+# ENV assignment patterns: KEY=value where KEY contains a secret-like name
+_SECRET_ENV_NAMES = r"(?:API_?KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|AUTH)"
+_ENV_ASSIGN_RE = re.compile(
+    rf"([A-Z_]*{_SECRET_ENV_NAMES}[A-Z_]*)\s*=\s*(['\"]?)(\S+)\2",
+    re.IGNORECASE,
+)
+
+# JSON field patterns: "apiKey": "value", "token": "value", etc.
+_JSON_KEY_NAMES = r"(?:api_?[Kk]ey|token|secret|password|access_token|refresh_token|auth_token|bearer|secret_value|raw_secret|secret_input|key_material)"
+_JSON_FIELD_RE = re.compile(
+    rf'("{_JSON_KEY_NAMES}")\s*:\s*"([^"]+)"',
+    re.IGNORECASE,
+)
+
+# Authorization headers
+_AUTH_HEADER_RE = re.compile(
+    r"(Authorization:\s*Bearer\s+)(\S+)",
+    re.IGNORECASE,
+)
+
+# Telegram bot tokens: bot<digits>:<token> or <digits>:<token>,
+# where token part is restricted to [-A-Za-z0-9_] and length >= 30
+_TELEGRAM_RE = re.compile(
+    r"(bot)?(\d{8,}):([-A-Za-z0-9_]{30,})",
+)
+
+# Private key blocks: -----BEGIN RSA PRIVATE KEY----- ... -----END RSA PRIVATE KEY-----
+_PRIVATE_KEY_RE = re.compile(
+    r"-----BEGIN[A-Z ]*PRIVATE KEY-----[\s\S]*?-----END[A-Z ]*PRIVATE KEY-----"
+)
+
+# Database connection strings: protocol://user:PASSWORD@host
+# Catches postgres, mysql, mongodb, redis, amqp URLs and redacts the password
+_DB_CONNSTR_RE = re.compile(
+    r"((?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis|amqp)://[^:]+:)([^@]+)(@)",
+    re.IGNORECASE,
+)
+
+# E.164 phone numbers: +<country><number>, 7-15 digits
+# Negative lookahead prevents matching hex strings or identifiers
+_SIGNAL_PHONE_RE = re.compile(r"(\+[1-9]\d{6,14})(?![A-Za-z0-9])")
+
+# Compile known prefix patterns into one alternation
+_PREFIX_RE = re.compile(
+    r"(?<![A-Za-z0-9_-])(" + "|".join(_PREFIX_PATTERNS) + r")(?![A-Za-z0-9_-])"
+)
+
+
+def _mask_token(token: str) -> str:
+    """Mask a token, preserving prefix for long tokens."""
+    if len(token) < 18:
+        return "***"
+    return f"{token[:6]}...{token[-4:]}"
+
+
+def redact_sensitive_text(text: str) -> str:
+    """Apply all redaction patterns to a block of text.
+
+    Safe to call on any string -- non-matching text passes through unchanged.
+    Disabled when security.redact_secrets is false in config.yaml.
+    """
+    if not text:
+        return text
+    # Redaction bypass is only honoured when COLONY_ENV=development to prevent
+    # accidental disablement in production via .env files or container env overrides.
+    if os.getenv("COLONY_REDACT_SECRETS", "").lower() in ("0", "false", "no", "off"):
+        colony_env = os.getenv("COLONY_ENV", "production").lower()
+        if colony_env != "development":
+            # Silently ignore the bypass flag in non-development environments.
+            pass
+        else:
+            import logging as _log
+            _log.getLogger(__name__).warning(
+                "COLONY_REDACT_SECRETS bypass is active — log redaction disabled. "
+                "This must NOT be set in production."
+            )
+            return text
+
+    # Known prefixes (sk-, ghp_, etc.)
+    text = _PREFIX_RE.sub(lambda m: _mask_token(m.group(1)), text)
+
+    # ENV assignments: OPENAI_API_KEY=sk-abc...
+    def _redact_env(m):
+        name, quote, value = m.group(1), m.group(2), m.group(3)
+        return f"{name}={quote}{_mask_token(value)}{quote}"
+    text = _ENV_ASSIGN_RE.sub(_redact_env, text)
+
+    # JSON fields: "apiKey": "value"
+    def _redact_json(m):
+        key, value = m.group(1), m.group(2)
+        return f'{key}: "{_mask_token(value)}"'
+    text = _JSON_FIELD_RE.sub(_redact_json, text)
+
+    # Authorization headers
+    text = _AUTH_HEADER_RE.sub(
+        lambda m: m.group(1) + _mask_token(m.group(2)),
+        text,
+    )
+
+    # Telegram bot tokens
+    def _redact_telegram(m):
+        prefix = m.group(1) or ""
+        digits = m.group(2)
+        return f"{prefix}{digits}:***"
+    text = _TELEGRAM_RE.sub(_redact_telegram, text)
+
+    # Private key blocks
+    text = _PRIVATE_KEY_RE.sub("[REDACTED PRIVATE KEY]", text)
+
+    # Database connection string passwords
+    text = _DB_CONNSTR_RE.sub(lambda m: f"{m.group(1)}***{m.group(3)}", text)
+
+    # E.164 phone numbers (Signal, WhatsApp)
+    def _redact_phone(m):
+        phone = m.group(1)
+        if len(phone) <= 8:
+            return phone[:2] + "****" + phone[-2:]
+        return phone[:4] + "****" + phone[-4:]
+    text = _SIGNAL_PHONE_RE.sub(_redact_phone, text)
+
+    return text
+
+
+class RedactingFormatter(logging.Formatter):
+    """Log formatter that redacts secrets from all log messages."""
+
+    def __init__(self, fmt=None, datefmt=None, style='%', **kwargs):
+        super().__init__(fmt, datefmt, style, **kwargs)
+
+    def format(self, record: logging.LogRecord) -> str:
+        original = super().format(record)
+        return redact_sensitive_text(original)

apsimo/repos/__init__.py

@@ -0,0 +1,5 @@
+"""Read-only repo mirrors + tools (owner-designated, boundary-gated)."""
+
+from apsimo.repos.mirrors import RepoMirrorManager, parse_mirror_config
+
+__all__ = ["RepoMirrorManager", "parse_mirror_config"]

apsimo/repos/mirrors.py

@@ -0,0 +1,204 @@
+"""Read-only local repo mirrors for Colony's own research (best-of-B).
+
+Owner-designated repos (env/config only, never hardcoded) are cloned/pulled
+into a local mirror directory. Colony gets low-latency read access -- list,
+read, search -- with NO write credentials anywhere. Every access is
+boundary-gated: a standing "leave X alone" blocks even reads of X.
+
+Config: COLONY_REPO_MIRRORS = "name=url[|alias1|alias2][,name2=url2...]"
+Mirror dir: <state_dir>/repo-mirrors/<name>
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import logging
+import os
+import subprocess
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+_MAX_READ_BYTES = 64 * 1024
+_SKIP_DIRS = {".git", "node_modules", "__pycache__", ".venv", "venv", "dist", "build"}
+
+
+def parse_mirror_config(raw: str) -> Dict[str, Dict[str, str]]:
+    """Parse COLONY_REPO_MIRRORS into {name: {url, aliases}}."""
+    out: Dict[str, Dict[str, str]] = {}
+    for part in (raw or "").split(","):
+        part = part.strip()
+        if not part or "=" not in part:
+            continue
+        name, rest = part.split("=", 1)
+        pieces = rest.split("|")
+        url = pieces[0].strip()
+        aliases = "|".join(a.strip() for a in pieces[1:] if a.strip())
+        if name.strip() and url:
+            out[name.strip()] = {"url": url, "aliases": aliases}
+    return out
+
+
+class RepoMirrorManager:
+    def __init__(
+        self,
+        mirror_dir: str,
+        config: Optional[Dict[str, Dict[str, str]]] = None,
+        directive_manager: Any = None,
+    ) -> None:
+        self._dir = Path(mirror_dir)
+        self._config = config if config is not None else parse_mirror_config(
+            os.environ.get("COLONY_REPO_MIRRORS", ""))
+        self._directives = directive_manager
+        self._last_refresh: Dict[str, float] = {}
+
+    def configured(self) -> Dict[str, Dict[str, str]]:
+        return dict(self._config)
+
+    def path_for(self, name: str) -> Optional[str]:
+        if name not in self._config:
+            return None
+        p = self._dir / name
+        return str(p) if (p / ".git").exists() or (p / "HEAD").exists() else None
+
+    # -- boundary gate --------------------------------------------------
+    def _boundary_ok(self, name: str, extra: str = "") -> Any:
+        if self._directives is None:
+            return None
+        try:
+            from apsimo.directives import Action
+            verdict = self._directives.check(Action(
+                kind="repo_read", text=f"{name} {extra}", target=name))
+            return verdict if not verdict.allowed else None
+        except Exception:
+            return None
+
+    # -- sync -------------------------------------------------------------
+    def refresh(self, name: str, min_interval_secs: float = 300.0) -> Dict[str, Any]:
+        """Clone or pull one mirror (read-only; no credentials added)."""
+        info = self._config.get(name)
+        if info is None:
+            return {"ok": False, "reason": "unknown_repo"}
+        blocked = self._boundary_ok(name, "refresh")
+        if blocked is not None:
+            return {"ok": False, "reason": blocked.reason}
+        now = time.time()
+        if now - self._last_refresh.get(name, 0) < min_interval_secs and self.path_for(name):
+            return {"ok": True, "action": "fresh"}
+        self._dir.mkdir(parents=True, exist_ok=True)
+        dest = self._dir / name
+        try:
+            if (dest / ".git").exists():
+                subprocess.run(["git", "-C", str(dest), "fetch", "--all", "--prune"],
+                               capture_output=True, text=True, timeout=120, check=True)
+                subprocess.run(["git", "-C", str(dest), "reset", "--hard", "@{upstream}"],
+                               capture_output=True, text=True, timeout=60, check=False)
+                action = "pulled"
+            else:
+                subprocess.run(["git", "clone", info["url"], str(dest)],
+                               capture_output=True, text=True, timeout=300, check=True)
+                action = "cloned"
+            self._last_refresh[name] = now
+            return {"ok": True, "action": action}
+        except subprocess.CalledProcessError as exc:
+            err = (exc.stderr or "")[:200]
+            logger.warning("mirror refresh failed for %s: %s", name, err)
+            return {"ok": False, "reason": err}
+        except Exception as exc:
+            return {"ok": False, "reason": str(exc)[:200]}
+
+    def refresh_all(self) -> Dict[str, Any]:
+        return {name: self.refresh(name) for name in self._config}
+
+    # -- read tools ---------------------------------------------------------
+    def list_files(self, name: str, subpath: str = "", limit: int = 200) -> Dict[str, Any]:
+        blocked = self._boundary_ok(name, subpath)
+        if blocked is not None:
+            return {"error": blocked.reason, "status": "boundary_refused"}
+        root = self.path_for(name)
+        if root is None:
+            return {"error": f"repo {name!r} not mirrored", "status": "unavailable"}
+        base = Path(root) / subpath.lstrip("/")
+        base_r = base.resolve()
+        if not str(base_r).startswith(str(Path(root).resolve())):
+            return {"error": "path escapes repo", "status": "error"}
+        if not base_r.exists():
+            return {"error": f"no such path {subpath!r}", "status": "not_found"}
+        files: List[str] = []
+        for p in sorted(base_r.rglob("*")):
+            rel_parts = p.relative_to(root).parts
+            if any(part in _SKIP_DIRS for part in rel_parts):
+                continue
+            if p.is_file():
+                files.append(str(p.relative_to(root)))
+                if len(files) >= limit:
+                    break
+        return {"repo": name, "path": subpath or "/", "count": len(files), "files": files}
+
+    def read_file(self, name: str, path: str, max_bytes: int = _MAX_READ_BYTES) -> Dict[str, Any]:
+        blocked = self._boundary_ok(name, path)
+        if blocked is not None:
+            return {"error": blocked.reason, "status": "boundary_refused"}
+        root = self.path_for(name)
+        if root is None:
+            return {"error": f"repo {name!r} not mirrored", "status": "unavailable"}
+        f = (Path(root) / path.lstrip("/")).resolve()
+        if not str(f).startswith(str(Path(root).resolve())):
+            return {"error": "path escapes repo", "status": "error"}
+        if not f.is_file():
+            return {"error": f"no such file {path!r}", "status": "not_found"}
+        try:
+            data = f.read_bytes()[: max(1024, min(max_bytes, _MAX_READ_BYTES))]
+            return {"repo": name, "path": path, "size": f.stat().st_size,
+                    "content": data.decode("utf-8", errors="replace")}
+        except Exception as exc:
+            return {"error": str(exc)[:200], "status": "error"}
+
+    def search(self, name: str, query: str, glob: str = "",
+               max_results: int = 40) -> Dict[str, Any]:
+        blocked = self._boundary_ok(name, query)
+        if blocked is not None:
+            return {"error": blocked.reason, "status": "boundary_refused"}
+        root = self.path_for(name)
+        if root is None:
+            return {"error": f"repo {name!r} not mirrored", "status": "unavailable"}
+        if not query:
+            return {"error": "query required", "status": "error"}
+        try:
+            args = ["git", "-C", root, "grep", "-In", "--max-depth", "-1", "-e", query]
+            if glob:
+                args += ["--", glob]
+            out = subprocess.run(args, capture_output=True, text=True, timeout=30)
+            lines = [ln for ln in out.stdout.splitlines() if ln.strip()][:max_results]
+            return {"repo": name, "query": query, "count": len(lines),
+                    "matches": lines}
+        except Exception as exc:
+            return {"error": str(exc)[:200], "status": "error"}
+
+    # -- world-model feed -----------------------------------------------------
+    async def register_entities(self, world_store: Any) -> int:
+        """Upsert each owner-designated repo as a Project entity (deterministic,
+        config-driven; not extraction guesswork)."""
+        if world_store is None:
+            return 0
+        n = 0
+        try:
+            from apsimo.world_model.entities import ProjectEntity
+            from apsimo.world_model.sqlite.backend import _generate_id
+            for name, info in self._config.items():
+                existing = await world_store.get_entity_by_external_id("repo_name", name)
+                if existing is not None:
+                    continue
+                ent = ProjectEntity(
+                    id=_generate_id("we"), name=name, entity_type="project",
+                    confidence=0.95,
+                    external_ids={"repo_name": name},
+                    properties={"kind": "repo", "url": info.get("url", "")},
+                )
+                await world_store.upsert_entity(ent)
+                n += 1
+        except Exception:
+            logger.debug("repo entity registration failed", exc_info=True)
+        return n

apsimo/research/__init__.py

@@ -0,0 +1,41 @@
+"""Colony Research-to-Artifact Pipeline (RAP).
+
+A unified, autonomy-capable pipeline that takes a research goal and produces
+a polished, gated deliverable with minimal human intervention.
+
+Six pipeline stages:
+  1. DECOMPOSE  — break goal into sub-tasks
+  2. GATHER     — collect evidence from web, graph, documents, email
+  3. SYNTHESIZE — cross-reference and extract insights
+  4. OUTLINE    — build structured artifact outline
+  5. PRODUCE    — render artifact in requested format
+  6. REVIEW     — quality and safety gate
+
+Usage::
+
+    from apsimo.research import ResearchPipeline, ArtifactFormat
+
+    pipeline = ResearchPipeline()
+    result = await pipeline.run(
+        goal="Research competitor pricing and produce a report",
+        format=ArtifactFormat.MARKDOWN,
+    )
+"""
+
+from apsimo.research.artifact import ArtifactFormat, Artifact
+from apsimo.research.gatherer import EvidenceItem, EvidencePackage, SourceType
+from apsimo.research.synthesizer import SynthesisReport
+from apsimo.research.pipeline import ResearchPipeline, PipelineRun, PipelineStage, PipelineStatus
+
+__all__ = [
+    "ResearchPipeline",
+    "PipelineRun",
+    "PipelineStage",
+    "PipelineStatus",
+    "ArtifactFormat",
+    "Artifact",
+    "EvidenceItem",
+    "EvidencePackage",
+    "SourceType",
+    "SynthesisReport",
+]