brown-octopus 0.4.4__py3-none-any.whl

brown_octopus/__init__.py

@@ -0,0 +1,24 @@
+from brown_octopus.octopus import Octopus
+from brown_octopus.config import OctopusConfig
+from brown_octopus.contracts import RetrievalResult
+from brown_octopus.contracts import (
+    CapabilityDiscoveryResult,
+    CapabilitySource,
+    SessionState,
+    SessionStore,
+)
+from brown_octopus.session_store import InMemorySessionStore
+from brown_octopus.sources import CapabilityUpdateReport, LocalMcpCatalogSource
+
+__all__ = [
+    "Octopus",
+    "OctopusConfig",
+    "RetrievalResult",
+    "CapabilitySource",
+    "SessionState",
+    "SessionStore",
+    "InMemorySessionStore",
+    "CapabilityDiscoveryResult",
+    "CapabilityUpdateReport",
+    "LocalMcpCatalogSource",
+]

brown_octopus/active_tools.py

@@ -0,0 +1,39 @@
+ACTIVE_TOOL_TTL = 8
+MAX_ACTIVE_TOOLS = 30
+
+
+def update_active_tools(
+    active_tools: dict[str, int],
+    retrieved_tools: list[str],
+    turn: int,
+    ttl: int = ACTIVE_TOOL_TTL,
+    max_active_tools: int = MAX_ACTIVE_TOOLS,
+) -> dict[str, int]:
+    updated_tools = active_tools.copy()
+
+    # Add newly retrieved tools and refresh
+    # tools that were retrieved again.
+    for tool_name in retrieved_tools:
+        updated_tools[tool_name] = turn
+
+    # Remove tools that have exceeded their TTL.
+    updated_tools = {
+        tool_name: last_retrieved_turn
+        for tool_name, last_retrieved_turn in updated_tools.items()
+        if turn - last_retrieved_turn <= ttl
+    }
+
+    # If the context is still too large,
+    # keep the most recently retrieved tools.
+    if len(updated_tools) > max_active_tools:
+        # When several capabilities were retrieved on the same turn, retain
+        # the later entries as the most recently encountered ones. This keeps
+        # the cap deterministic and evicts the oldest entry first.
+        indexed = list(enumerate(updated_tools.items()))
+        indexed.sort(key=lambda item: (item[1][1], item[0]), reverse=True)
+        updated_tools = dict(item for _, item in indexed[:max_active_tools])
+
+    return updated_tools
+
+
+

brown_octopus/analyzer.py

@@ -0,0 +1,296 @@
+import spacy
+from spacy.language import Language
+from spacy.tokens import Doc, Token
+
+from brown_octopus.model_store import register_managed_spacy_plugins, resolve_spacy_model
+
+
+SPACY_MODEL_NAME = "en_core_web_trf"
+OBJECT_DEPENDENCIES = {"dobj", "obj", "attr"}
+
+nlp: Language | None = None
+
+
+class DeterministicIntentAnalyzer:
+    """Interface adapter for the current deterministic spaCy analyzer."""
+
+    name = "spacy_deterministic"
+
+    def analyze(self, text: str) -> list[dict]:
+        return analyze_intents(text)
+
+
+def initialize_analyzer() -> None:
+    """Load the spaCy model once."""
+    global nlp
+
+    if nlp is None:
+        register_managed_spacy_plugins()
+        nlp = spacy.load(resolve_spacy_model())
+
+
+def _has_direct_object(token: Token) -> bool:
+    return any(child.dep_ in OBJECT_DEPENDENCIES for child in token.children)
+
+
+def _find_action_tokens(doc: Doc) -> list[Token]:
+    root = next(token for token in doc if token.dep_ == "ROOT")
+
+    action_tokens = [root]
+
+    action_tokens.extend(
+        token for token in doc if token.dep_ == "conj" and token.pos_ == "VERB"
+    )
+
+    action_tokens.extend(
+        token
+        for token in doc
+        if token.dep_ == "dep"
+        and token.pos_ == "VERB"
+        and token.head == root
+        and _has_direct_object(token)
+    )
+
+    action_tokens.extend(
+        token
+        for token in doc
+        if token.dep_ == "acl" and token.pos_ == "VERB" and _has_direct_object(token)
+    )
+
+    return sorted(
+        set(action_tokens),
+        key=lambda token: token.i,
+    )
+
+
+def _belongs_to_nested_action(
+    token: Token,
+    action_token: Token,
+    action_tokens: list[Token],
+) -> bool:
+    action_subtree = set(action_token.subtree)
+
+    return any(
+        other_action != action_token
+        and other_action in action_subtree
+        and (token == other_action or other_action in token.ancestors)
+        for other_action in action_tokens
+    )
+
+
+def _get_local_text(
+    action_token: Token,
+    action_tokens: list[Token],
+) -> str:
+    local_tokens = []
+
+    for token in action_token.subtree:
+        if token.is_punct:
+            continue
+
+        if token.dep_ == "cc":
+            continue
+
+        if _belongs_to_nested_action(
+            token,
+            action_token,
+            action_tokens,
+        ):
+            continue
+
+        local_tokens.append(token)
+
+    local_tokens.sort(key=lambda token: token.i)
+
+    return " ".join(token.text for token in local_tokens)
+
+
+def _get_direct_target(
+    action_token: Token,
+    action_tokens: list[Token],
+) -> str | None:
+    targets = []
+
+    for child in action_token.children:
+        if child.dep_ not in OBJECT_DEPENDENCIES:
+            continue
+
+        target_tokens = []
+
+        for token in child.subtree:
+            if token.is_punct:
+                continue
+
+            if _belongs_to_nested_action(
+                token,
+                action_token,
+                action_tokens,
+            ):
+                continue
+
+            target_tokens.append(token)
+
+        target_tokens.sort(key=lambda token: token.i)
+
+        target_text = " ".join(token.text for token in target_tokens).strip()
+
+        if target_text:
+            targets.append(target_text)
+
+    if not targets:
+        return None
+
+    return " ".join(targets)
+
+
+def _get_core_resource(action_token: Token) -> str | None:
+    """Return the core grammatical resource operated on by an action.
+
+    This intentionally uses only dependency structure.  Task-specific
+    arguments such as names, titles, and dates remain in the normal intent
+    fields but do not become part of the capability retrieval query.
+    """
+
+    def collect_compounds(token: Token) -> list[Token]:
+        compounds: list[Token] = []
+        for child in token.children:
+            if child.dep_ == "compound":
+                compounds.extend(collect_compounds(child))
+                compounds.append(child)
+        return compounds
+
+    for child in action_token.children:
+        if child.dep_ not in OBJECT_DEPENDENCIES:
+            continue
+
+        tokens = collect_compounds(child) + [child]
+        tokens.sort(key=lambda token: token.i)
+        resource = " ".join(token.text for token in tokens).strip()
+        if resource:
+            return resource
+
+    # Handle constructions such as "reply to the email".
+    for child in action_token.children:
+        if child.dep_ not in {"prep", "dative"}:
+            continue
+
+        for token in child.subtree:
+            if token.dep_ != "pobj" or token.pos_ not in {"NOUN", "PROPN"}:
+                continue
+
+            tokens = collect_compounds(token) + [token]
+            tokens.sort(key=lambda item: item.i)
+            resource = " ".join(item.text for item in tokens).strip()
+            if resource:
+                return resource
+
+    return None
+
+
+def _get_retrieval_text(action_token: Token) -> str:
+    """Build the compact capability-oriented query for one intent."""
+
+    resource = _get_core_resource(action_token)
+    if not resource:
+        return action_token.lemma_
+    return f"{action_token.lemma_} {resource}"
+
+
+def _get_fallback_target(
+    doc: Doc,
+    action_token: Token,
+    action_tokens: list[Token],
+) -> str | None:
+    action_index = action_token.i
+
+    later_actions = [token.i for token in action_tokens if token.i > action_index]
+
+    end_index = min(later_actions) if later_actions else len(doc)
+
+    candidates = [
+        token
+        for token in doc[action_index:end_index]
+        if token.pos_ in {"NOUN", "PROPN"}
+    ]
+
+    if not candidates:
+        return None
+
+    return " ".join(token.text for token in candidates)
+
+
+def analyze_intents(text: str) -> list[dict]:
+    """
+    Decompose a user request into operational intents.
+    """
+    if nlp is None:
+        raise RuntimeError(
+            "Analyzer is not initialized. "
+            "Call initialize() before processing requests."
+        )
+
+    original_text = text.strip()
+
+    if not original_text:
+        return []
+
+    normalized_text = original_text[0].upper() + original_text[1:]
+
+    doc = nlp(normalized_text)
+
+    try:
+        action_tokens = _find_action_tokens(doc)
+    except StopIteration:
+        # Some short, mathematical, or malformed benchmark strings can be
+        # parsed without a ROOT. Preserve the request as one opaque intent so
+        # retrieval remains available instead of crashing the service.
+        return [
+            {
+                "action": "request",
+                "target": None,
+                "text": original_text,
+                "retrieval_text": original_text,
+                "context": original_text,
+            }
+        ]
+
+    if not action_tokens:
+        return [
+            {
+                "action": "request",
+                "target": None,
+                "text": original_text,
+                "retrieval_text": original_text,
+                "context": original_text,
+            }
+        ]
+
+    intents = []
+
+    for action_token in action_tokens:
+        target = _get_direct_target(
+            action_token,
+            action_tokens,
+        )
+
+        if target is None:
+            target = _get_fallback_target(
+                doc,
+                action_token,
+                action_tokens,
+            )
+
+        intents.append(
+            {
+                "action": action_token.lemma_,
+                "target": target,
+                "text": _get_local_text(
+                    action_token,
+                    action_tokens,
+                ),
+                "retrieval_text": _get_retrieval_text(action_token),
+                "context": original_text,
+            }
+        )
+
+    return intents

brown_octopus/bootstrap.py

@@ -0,0 +1,35 @@
+from pathlib import Path
+
+from brown_octopus.analyzer import initialize_analyzer
+from brown_octopus.mcp_discovery import discover_universe
+from brown_octopus.retriever import (
+    initialize_retriever,
+    refresh_index,
+)
+from brown_octopus.sources import load_mcp_urls
+from brown_octopus.tool_registry import set_tools
+
+
+DEFAULT_MCP_CATALOG = Path("data/mcps.json")
+
+
+async def initialize(
+    catalog_path: str | Path = DEFAULT_MCP_CATALOG,
+) -> list[dict]:
+    """
+    Initialize Brown Octopus and prepare it for requests.
+
+    Loads runtime models, discovers the available MCP tools,
+    populates the registry, and builds the retrieval index.
+    """
+    initialize_analyzer()
+    initialize_retriever()
+
+    mcp_urls = load_mcp_urls(catalog_path)
+
+    tools = await discover_universe(mcp_urls)
+
+    set_tools(tools)
+    refresh_index()
+
+    return tools

brown_octopus/cli.py

@@ -0,0 +1,220 @@
+"""Small, dependency-light command line interface for Brown Octopus."""
+
+import argparse
+import json
+import subprocess
+import sys
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+from brown_octopus.config import OctopusConfig
+from brown_octopus.model_store import (
+    EMBEDDING_MODEL_NAME,
+)
+
+
+DESCRIPTION = "Capability context management for AI agents."
+MODEL_DOCTOR_TIMEOUT_SECONDS = 180
+EMBEDDING_DOCTOR_TIMEOUT_SECONDS = 120
+
+
+def _version() -> str:
+    try:
+        return version("brown-octopus")
+    except PackageNotFoundError:
+        return "0.4.4"
+
+
+def _run_probe(code: str, timeout: int = 120) -> tuple[bool, str]:
+    try:
+        result = subprocess.run(
+            [sys.executable, "-c", code],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return False, str(exc)
+    output = (result.stdout or result.stderr).strip()
+    return result.returncode == 0, output
+
+
+def _index_details(index_path: Path) -> dict:
+    details = {"path": str(index_path), "exists": index_path.exists()}
+    if not index_path.exists():
+        return details
+    pointer = index_path / "current.json"
+    active = index_path
+    if pointer.exists():
+        try:
+            active = index_path / json.loads(pointer.read_text(encoding="utf-8"))["snapshot"]
+        except (OSError, KeyError, TypeError, json.JSONDecodeError) as exc:
+            details["error"] = f"invalid current.json: {exc}"
+            return details
+    metadata_path = active / "metadata.json"
+    details.update(
+        {
+            "active_path": str(active),
+            "metadata": metadata_path.exists(),
+            "tools": (active / "tools.json").exists(),
+            "embeddings": (active / "embeddings.pt").exists(),
+        }
+    )
+    if metadata_path.exists():
+        try:
+            metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
+            details.update(
+                {
+                    "index_version": metadata.get("version"),
+                    "tool_count": metadata.get("tool_count"),
+                    "embedding_model": metadata.get("embedding_model"),
+                    "brown_octopus_version": metadata.get("brown_octopus_version"),
+                }
+            )
+        except (OSError, json.JSONDecodeError) as exc:
+            details["error"] = f"invalid metadata.json: {exc}"
+    return details
+
+
+def _doctor() -> int:
+    config = OctopusConfig.from_env()
+    package_ok, package_output = _run_probe("import brown_octopus")
+    spacy_ok, _ = _run_probe(
+        "from brown_octopus.analyzer import initialize_analyzer; "
+        "initialize_analyzer(); print('en_core_web_trf')",
+        timeout=MODEL_DOCTOR_TIMEOUT_SECONDS,
+    )
+    qwen_ok, _ = _run_probe(
+        "from huggingface_hub import try_to_load_from_cache; "
+        f"p=try_to_load_from_cache({EMBEDDING_MODEL_NAME!r}, 'config.json'); "
+        "assert p is not None; print(p)",
+        timeout=EMBEDDING_DOCTOR_TIMEOUT_SECONDS,
+    )
+    index = _index_details(config.index_path)
+    index_ok = all(index.get(key, False) for key in ("metadata", "tools", "embeddings"))
+    index_ok = index_ok and index.get("index_version") == 1
+    healthy = package_ok and spacy_ok and qwen_ok and index_ok
+
+    print("Brown Octopus Doctor\n")
+    print("Package")
+    mark = lambda ok: "[OK]" if ok else "[FAIL]"
+    print(f"  {mark(package_ok)} brown-octopus {_version()}")
+    print(f"  {mark(package_ok)} Python {sys.version.split()[0]}")
+    print("\nModels")
+    print(f"  {mark(spacy_ok)} en_core_web_trf")
+    print(f"  {mark(qwen_ok)} Qwen/Qwen3-Embedding-0.6B")
+    print("\nIndex")
+    print(f"  {mark(index.get('exists', False))} index found: {config.index_path}")
+    print(f"  {mark(index_ok)} compatible index version")
+    if index.get("tool_count") is not None:
+        print(f"  {mark(index_ok)} {index['tool_count']} capabilities")
+    if not healthy:
+        print("\nFix:")
+        if not spacy_ok or not qwen_ok:
+            print("  brown-octopus setup-models")
+        if not index_ok:
+            print("  Build or provide a valid index with: await octopus.update()")
+        if not package_ok and package_output:
+            print(f"  Import diagnostic: {package_output.splitlines()[-1]}")
+        print("\nStatus\n  [FAIL] Brown Octopus is not ready.")
+        return 1
+    print("\nStatus\n  [OK] Brown Octopus is ready.")
+    return 0
+
+
+def _inspect(as_json: bool) -> int:
+    config = OctopusConfig.from_env()
+    index = _index_details(config.index_path)
+    data = {
+        "product": "Brown Octopus",
+        "version": _version(),
+        "capabilities": index.get("tool_count"),
+        "index_version": index.get("index_version"),
+        "index_path": str(config.index_path),
+        "embedding_model": index.get("embedding_model") or EMBEDDING_MODEL_NAME,
+        "analyzer": "deterministic-spacy",
+        "selector": "V3 Min-4 + Bounded Max Gap",
+        "ttl": config.ttl,
+        "active_cap": config.active_cap,
+    }
+    if as_json:
+        print(json.dumps(data, indent=2))
+        return 0
+    print("Brown Octopus\n")
+    for key, label in (
+        ("version", "Version"),
+        ("capabilities", "Capabilities"),
+        ("index_version", "Index version"),
+        ("embedding_model", "Embedding"),
+        ("analyzer", "Analyzer"),
+        ("selector", "Selector"),
+        ("ttl", "TTL"),
+        ("active_cap", "Active cap"),
+    ):
+        print(f"{label + ':':16} {data[key]}")
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="brown-octopus",
+        usage="brown-octopus COMMAND",
+        description=f"Brown Octopus - {DESCRIPTION}",
+        epilog=(
+            "Quick start:\n"
+            "  pip install brown-octopus\n"
+            "  brown-octopus setup-models\n"
+            "  from brown_octopus import Octopus"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {_version()}")
+    subparsers = parser.add_subparsers(dest="command")
+    setup = subparsers.add_parser(
+        "setup-models",
+        help="Prepare the models required by Octopus.",
+        description=(
+            "Download and validate en_core_web_trf and "
+            "Qwen/Qwen3-Embedding-0.6B.\n"
+            "Model setup is explicit; initialize() never downloads models."
+        ),
+    )
+    setup.set_defaults(handler="setup-models")
+    doctor = subparsers.add_parser("doctor", help="Check whether Brown Octopus is ready.")
+    doctor.set_defaults(handler="doctor")
+    inspect = subparsers.add_parser(
+        "inspect", help="Inspect the local index and runtime configuration."
+    )
+    inspect.add_argument("--json", action="store_true", help="Emit machine-readable JSON.")
+    inspect.set_defaults(handler="inspect")
+    version_parser = subparsers.add_parser("version", help="Display version information.")
+    version_parser.set_defaults(handler="version")
+    return parser
+
+
+def main() -> int:
+    parser = _build_parser()
+    args = parser.parse_args()
+    handler = getattr(args, "handler", None)
+    try:
+        if handler == "setup-models":
+            from brown_octopus.setup_models import main as setup_models
+
+            setup_models()
+            return 0
+        if handler == "doctor":
+            return _doctor()
+        if handler == "inspect":
+            return _inspect(args.json)
+        if handler == "version":
+            print(f"brown-octopus {_version()}")
+            return 0
+        parser.print_help()
+        return 0
+    except Exception as exc:
+        print(f"Brown Octopus: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

brown_octopus/config.py

@@ -0,0 +1,44 @@
+"""Runtime configuration loaded from environment variables."""
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+def _int(name: str, default: int) -> int:
+    value = os.getenv(name)
+    return default if value is None else int(value)
+
+
+def _float(name: str, default: float) -> float:
+    value = os.getenv(name)
+    return default if value is None else float(value)
+
+
+@dataclass(frozen=True)
+class OctopusConfig:
+    index_path: Path = Path("data/indexes/default")
+    catalog_path: Path = Path("data/mcps.json")
+    ttl: int = 8
+    active_cap: int = 30
+    min_tools: int = 4
+    max_tools: int = 16
+    min_gap_percent: float = 2.0
+    log_level: str = "INFO"
+
+    @classmethod
+    def from_env(cls) -> "OctopusConfig":
+        return cls(
+            index_path=Path(os.getenv("OCTOPUS_INDEX_PATH", "data/indexes/default")),
+            catalog_path=Path(os.getenv("OCTOPUS_CATALOG_PATH", "data/mcps.json")),
+            ttl=_int("OCTOPUS_CAPABILITY_TTL", 8),
+            active_cap=_int("OCTOPUS_ACTIVE_CAP", 30),
+            min_tools=_int("OCTOPUS_MIN_TOOLS", 4),
+            max_tools=_int("OCTOPUS_MAX_TOOLS", 16),
+            min_gap_percent=_float("OCTOPUS_MIN_GAP_PERCENT", 2.0),
+            log_level=os.getenv("OCTOPUS_LOG_LEVEL", "INFO"),
+        )
+
+    def validate(self) -> None:
+        if self.ttl < 0 or self.active_cap < 1:
+            raise ValueError("TTL and active capability cap must be valid")