foo-mcp 0.1.0__py3-none-any.whl

foo_mcp/__init__.py

@@ -0,0 +1,12 @@
+"""FOO MCP — multiagent orchestration as a Model Context Protocol server."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("foo-mcp")
+except PackageNotFoundError:
+    __version__ = "0.0.0+local"
+
+__all__ = ["__version__"]

foo_mcp/_data/foo.agents.example.json

@@ -0,0 +1,65 @@
+{
+  "schema_version": "foo.config.v1",
+  "CONFIG": {
+    "instructions": "You are part of a transparent multiagent review system. Provide specific, evidence-oriented feedback and avoid unsupported claims.",
+    "name": "FOO MCP",
+    "user": "Researcher",
+    "output_dir": "runs",
+    "trace_include_raw_content": true
+  },
+  "MODELS": [
+    {
+      "agent_name": "Reviewer_A",
+      "provider": "mock",
+      "model_code": "mock-reviewer-a",
+      "model_name": "Deterministic Mock Reviewer A",
+      "temperature": 0.1,
+      "max_completion_tokens": 1000,
+      "harmonizer": false,
+      "agent_directive": "Focus on methodological flaws, traceability, and reproducibility."
+    },
+    {
+      "agent_name": "Reviewer_B",
+      "provider": "mock",
+      "model_code": "mock-reviewer-b",
+      "model_name": "Deterministic Mock Reviewer B",
+      "temperature": 0.3,
+      "max_completion_tokens": 1000,
+      "harmonizer": false,
+      "agent_directive": "Focus on assumptions, alternative interpretations, and missing evidence."
+    },
+    {
+      "agent_name": "Harmonizer",
+      "provider": "mock",
+      "model_code": "mock-harmonizer",
+      "model_name": "Deterministic Mock Harmonizer",
+      "temperature": 0.0,
+      "max_completion_tokens": 1500,
+      "harmonizer": true,
+      "harmonizer_directive": "Organize peer feedback for {source_agent_name} into Agreement, Disagreement, and Unique Observations. Preserve each observation without summarizing away detail.",
+      "agent_directive": "Preserve reviewer-specific detail and label all claims by source agent."
+    },
+    {
+      "agent_name": "HF_Disabled_Example",
+      "provider": "huggingface",
+      "model_code": "Qwen/Qwen2.5-7B-Instruct",
+      "model_name": "Hugging Face hosted inference example",
+      "temperature": 0.1,
+      "top_p": 0.95,
+      "max_completion_tokens": 1000,
+      "active": false,
+      "agent_directive": "Enable this agent after setting HF_TOKEN or logging in with Hugging Face tooling."
+    },
+    {
+      "agent_name": "MLX_Disabled_Example",
+      "provider": "mlx",
+      "model_code": "mlx-community/Llama-3.2-3B-Instruct-4bit",
+      "model_name": "Apple Silicon MLX local inference example",
+      "temperature": 0.0,
+      "max_completion_tokens": 512,
+      "max_kv_size": 4096,
+      "active": false,
+      "agent_directive": "Enable this agent on Apple Silicon after installing the mlx optional extra."
+    }
+  ]
+}

foo_mcp/config.py

@@ -0,0 +1,290 @@
+"""Typed configuration for the FOO MCP server."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from foo_mcp.schemas import ProviderName
+
+DEFAULT_CONFIG_PATH = Path("config/foo.agents.example.json")
+_PACKAGE_DIR = Path(__file__).resolve().parent
+_BUNDLED_CONFIG_PATH = _PACKAGE_DIR / "_data" / "foo.agents.example.json"
+BUNDLED_CONFIG_PATH = _BUNDLED_CONFIG_PATH
+
+
+class FooSettings(BaseModel):
+    """Global settings from the legacy FOO CONFIG block plus MCP additions."""
+
+    instructions: str
+    name: str = "FOO MCP"
+    user: str = "Researcher"
+    model: str | None = None
+    cwd: str | None = Field(default=None, alias="CWD")
+    output_dir: str = "runs"
+    trace_include_raw_content: bool = True
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+
+class AgentSpec(BaseModel):
+    """One configured agent."""
+
+    agent_name: str
+    model_code: str
+    provider: ProviderName | None = None
+    model_name: str | None = None
+    temperature: float | None = None
+    max_completion_tokens: int | None = None
+    top_p: float | None = None
+    top_k: int | None = None
+    min_p: float | None = None
+    max_kv_size: int | None = None
+    huggingface_provider: str | None = None
+    endpoint_url: str | None = None
+    endpoint_model: str | None = None
+    trust_remote_code: bool = False
+    eos_token: str | None = None
+    harmonizer: bool = False
+    harmonizer_directive: str = ""
+    agent_directive: str = ""
+    active: bool = True
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    @field_validator("harmonizer", mode="before")
+    @classmethod
+    def parse_boolish(cls, value: Any) -> bool:
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, str):
+            return value.strip().lower() in {"1", "true", "yes", "y"}
+        return bool(value)
+
+    @field_validator("provider", mode="before")
+    @classmethod
+    def normalize_provider(cls, value: Any) -> ProviderName | None:
+        if value is None or value == "":
+            return None
+        normalized = str(value).strip().lower()
+        aliases = {
+            "claude": "anthropic",
+            "anthropic": "anthropic",
+            "gemini": "google",
+            "google": "google",
+            "hf": "huggingface",
+            "huggingface": "huggingface",
+            "hugging-face": "huggingface",
+            "hugging_face": "huggingface",
+            "local_mlx": "mlx",
+            "mlx": "mlx",
+            "mlx-lm": "mlx",
+            "mlx_lm": "mlx",
+            "openai": "openai",
+            "mock": "mock",
+        }
+        if normalized not in aliases:
+            raise ValueError(f"Unsupported provider '{value}'")
+        return aliases[normalized]  # type: ignore[return-value]
+
+    @property
+    def resolved_provider(self) -> ProviderName:
+        if self.provider:
+            return self.provider
+        model = self.model_code.lower()
+        if model.startswith("claude"):
+            return "anthropic"
+        if model.startswith("gemini"):
+            return "google"
+        if model.startswith("mlx-community/") or model.startswith("mlx_"):
+            return "mlx"
+        if model.startswith("hf_"):
+            return "huggingface"
+        if model.startswith("mock"):
+            return "mock"
+        return "openai"
+
+
+class FooConfig(BaseModel):
+    """Root FOO config model."""
+
+    schema_version: str = "foo.config.v1"
+    settings: FooSettings = Field(alias="CONFIG")
+    models: list[AgentSpec] = Field(alias="MODELS")
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    @model_validator(mode="after")
+    def validate_agent_names(self) -> FooConfig:
+        names = [agent.agent_name for agent in self.models]
+        duplicates = sorted({name for name in names if names.count(name) > 1})
+        if duplicates:
+            raise ValueError(f"Duplicate agent names: {', '.join(duplicates)}")
+        if not self.models:
+            raise ValueError("At least one agent must be configured")
+        return self
+
+    def sanitized(self) -> dict[str, Any]:
+        data = self.model_dump(by_alias=True)
+        data["CONFIG"].pop("blockchain_salt", None)
+        return data
+
+
+def load_dotenv_if_available() -> None:
+    try:
+        from dotenv import load_dotenv
+    except ImportError:
+        return
+    load_dotenv()
+
+
+def resolve_config_path(config_path: str | Path | None = None) -> Path:
+    if config_path:
+        return Path(config_path).expanduser()
+    env_path = os.getenv("FOO_MCP_CONFIG")
+    if env_path:
+        path = Path(env_path).expanduser()
+        if path.exists():
+            return path
+        print(
+            f"[foo-mcp] warning: FOO_MCP_CONFIG={env_path!r} does not exist; "
+            "falling back to bundled example.",
+            file=sys.stderr,
+        )
+    # Fall back to the example shipped inside the package.
+    return _BUNDLED_CONFIG_PATH
+
+
+def load_config(config_path: str | Path | None = None) -> FooConfig:
+    load_dotenv_if_available()
+    path = resolve_config_path(config_path)
+    with path.open("r", encoding="utf-8") as handle:
+        payload = json.load(handle)
+    return FooConfig.model_validate(payload)
+
+
+def clean_api_key(value: str | None) -> str | None:
+    """Strip surrounding whitespace and matching wrapping quotes from a key.
+
+    .env loaders and shell exports occasionally leave keys quoted (KEY="sk-..."),
+    sometimes with nested layers (KEY="'sk-...'"). Repeatedly strip matched
+    outer quotes until none remain. Mismatched and interior quotes are kept.
+    """
+    if value is None:
+        return None
+    cleaned = value.strip()
+    while len(cleaned) >= 2 and cleaned[0] == cleaned[-1] and cleaned[0] in ('"', "'"):
+        cleaned = cleaned[1:-1].strip()
+    return cleaned or None
+
+
+def get_clean_env(name: str) -> str | None:
+    return clean_api_key(os.getenv(name))
+
+
+def env_key_for_provider(provider: ProviderName) -> tuple[str, ...]:
+    if provider == "openai":
+        return ("OPENAI_API_KEY",)
+    if provider == "anthropic":
+        return ("ANTHROPIC_API_KEY",)
+    if provider == "google":
+        return ("GEMINI_API_KEY", "GOOGLE_API_KEY")
+    if provider == "huggingface":
+        return ("HF_TOKEN", "HUGGINGFACE_API_KEY", "HUGGINGFACE_HUB_TOKEN")
+    return ()
+
+
+def missing_env_keys_for_agent(agent: AgentSpec) -> list[str]:
+    if agent.resolved_provider == "huggingface" and agent.endpoint_url:
+        return []
+    if agent.resolved_provider == "mlx":
+        return []
+    candidates = env_key_for_provider(agent.resolved_provider)
+    if not candidates:
+        return []
+    if any(get_clean_env(name) for name in candidates):
+        return []
+    return list(candidates)
+
+
+def is_bundled_example(path: str | Path) -> bool:
+    """True if ``path`` resolves to the bundled in-package example config."""
+    try:
+        return Path(path).expanduser().resolve() == BUNDLED_CONFIG_PATH.resolve()
+    except OSError:
+        return False
+
+
+def count_usable_real_agents(config: FooConfig) -> tuple[int, list[str], list[str]]:
+    """Return (count, usable_names, blocked_reasons).
+
+    Usable = active, non-mock, with no missing provider env keys (or local mlx).
+    blocked_reasons names every active non-mock agent that isn't usable along with
+    the reason (missing key or inactive — though inactive is filtered earlier).
+    """
+    usable: list[str] = []
+    blocked: list[str] = []
+    for agent in config.models:
+        if agent.resolved_provider == "mock":
+            continue
+        if not agent.active:
+            blocked.append(f"{agent.agent_name}: inactive")
+            continue
+        missing = missing_env_keys_for_agent(agent)
+        if missing:
+            blocked.append(f"{agent.agent_name}: missing {' or '.join(missing)}")
+            continue
+        usable.append(agent.agent_name)
+    return len(usable), usable, blocked
+
+
+def validate_runtime_agents(
+    config: FooConfig,
+    config_path: str | Path,
+    *,
+    allow_single_real: bool,
+) -> tuple[bool, str | None]:
+    """Check whether the active config has enough usable real agents to run.
+
+    Returns ``(ok, error_message)``. Skips enforcement when:
+      - ``allow_single_real`` is True (env-var escape hatch), OR
+      - ``config_path`` resolves to the bundled in-package example (so the
+        zero-key default flow continues to work).
+    Otherwise requires at least 2 usable non-mock agents.
+    """
+    if allow_single_real:
+        return True, None
+    if is_bundled_example(config_path):
+        return True, None
+    count, usable, blocked = count_usable_real_agents(config)
+    if count >= 2:
+        return True, None
+    lines = [
+        f"foo-mcp requires at least 2 usable non-mock agents to start (found {count}).",
+        f"  Usable:  {', '.join(usable) if usable else '(none)'}",
+        f"  Blocked: {', '.join(blocked) if blocked else '(none)'}",
+        "",
+        "Fix options:",
+        "  1. Run 'foo-mcp-init' to generate a working config interactively.",
+        "  2. Export the missing API keys for the providers listed above.",
+        "  3. For testing only, set FOO_MCP_ALLOW_SINGLE_PROVIDER=1 to bypass.",
+    ]
+    return False, "\n".join(lines)
+
+
+def build_system_prompt(settings: FooSettings, agent: AgentSpec) -> str:
+    preamble = (
+        f"Address the user as Dr. {settings.user}.\n\n"
+        f"Introduce yourself as {agent.agent_name}, AI assistant.\n\n"
+    )
+    directive = (
+        f"\n\nAgent specific instructions:\n{agent.agent_directive}\n"
+        if agent.agent_directive
+        else ""
+    )
+    return preamble + settings.instructions + directive

foo_mcp/consensus_demo.py

@@ -0,0 +1,291 @@
+"""End-to-end consensus demo for foo-mcp.
+
+Runs the multi-agent pipeline (broadcast -> vulnerability -> judgment -> reflection -> verify
+-> export) against the configured agents and prints a structured report ending with the
+harmonizer's consensus and the source agent's revised answer.
+
+Usage::
+
+    foo-mcp-consensus-demo --question "What is the half-life of caffeine?"
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from foo_mcp.config import (
+    load_config,
+    load_dotenv_if_available,
+    resolve_config_path,
+    validate_runtime_agents,
+)
+from foo_mcp.orchestrator import FooOrchestrator
+from foo_mcp.tracing import TraceStore
+
+DEFAULT_QUESTION = (
+    "What is the recommended daily caffeine intake for a healthy adult, "
+    "and what is the typical half-life in plasma?"
+)
+
+
+@dataclass
+class DemoArgs:
+    question: str | None
+    config_path: Path | None
+    destination: Path | None
+    max_chars: int
+    json_only: bool
+    allow_single_real: bool
+    source_agent: str | None
+
+
+def parse_args(argv: list[str] | None = None) -> DemoArgs:
+    parser = argparse.ArgumentParser(
+        prog="foo-mcp-consensus-demo",
+        description=(
+            "Drive the full foo-mcp pipeline once and print a consensus report. "
+            "Useful as a smoke test that the configured providers can be reached."
+        ),
+    )
+    parser.add_argument("--question", help="Question to ask the agents (default: caffeine prompt).")
+    parser.add_argument(
+        "--config",
+        dest="config_path",
+        type=lambda s: Path(s).expanduser(),
+        help="Path to FooConfig JSON. Defaults to FOO_MCP_CONFIG / bundled example.",
+    )
+    parser.add_argument(
+        "--destination",
+        type=lambda s: Path(s).expanduser(),
+        help="Optional destination directory for the exported run bundle.",
+    )
+    parser.add_argument(
+        "--max-chars",
+        type=int,
+        default=280,
+        help="Snippet character limit per reviewer response (default: 280).",
+    )
+    parser.add_argument(
+        "--json-only",
+        action="store_true",
+        help="Emit one machine-readable JSON blob and skip the human report.",
+    )
+    parser.add_argument(
+        "--allow-single-real",
+        action="store_true",
+        help="Bypass the >=2 real providers requirement.",
+    )
+    parser.add_argument(
+        "--source-agent",
+        help="Override the auto-picked source agent (default: first active non-harmonizer).",
+    )
+    namespace = parser.parse_args(argv)
+    return DemoArgs(
+        question=namespace.question,
+        config_path=namespace.config_path,
+        destination=namespace.destination,
+        max_chars=max(80, namespace.max_chars),
+        json_only=namespace.json_only,
+        allow_single_real=namespace.allow_single_real,
+        source_agent=namespace.source_agent,
+    )
+
+
+def read_question(args: DemoArgs) -> str:
+    if args.question:
+        return args.question
+    if not sys.stdin.isatty():
+        data = sys.stdin.read().strip()
+        if data:
+            return data
+    return DEFAULT_QUESTION
+
+
+def shorten(text: str | None, max_chars: int) -> str:
+    if not text:
+        return "(no content)"
+    collapsed = " ".join(text.split())
+    if len(collapsed) <= max_chars:
+        return collapsed
+    return collapsed[: max_chars - 1].rstrip() + "…"
+
+
+def print_section(title: str) -> None:
+    print(f"\n=== {title} ===")
+
+
+def _fmt_latency(latency_ms: float | None) -> str:
+    if latency_ms is None:
+        return "   ?ms"
+    return f"{int(latency_ms):>5d}ms"
+
+
+def print_response_row(response: dict[str, Any], max_chars: int) -> None:
+    name = response.get("agent_name", "?")
+    provider = response.get("provider", "?")
+    model = response.get("model", "?")
+    latency = _fmt_latency(response.get("latency_ms"))
+    snippet = shorten(response.get("content"), max_chars)
+    error = response.get("error")
+    suffix = f"  [ERROR: {error}]" if error else ""
+    print(f"  {name:<22} | {provider}:{model} | {latency} | {snippet}{suffix}")
+
+
+def print_full_response(response: dict[str, Any], max_chars: int) -> None:
+    name = response.get("agent_name", "?")
+    provider = response.get("provider", "?")
+    model = response.get("model", "?")
+    latency = _fmt_latency(response.get("latency_ms"))
+    print(f"  {name:<22} | {provider}:{model} | {latency}")
+    if response.get("error"):
+        print(f"  ERROR: {response['error']}")
+        return
+    content = response.get("content") or "(no content)"
+    print()
+    if len(content) <= max_chars:
+        print(content)
+    else:
+        print(content[: max_chars - 1].rstrip() + "…")
+
+
+def pick_source_agent(orchestrator: FooOrchestrator, override: str | None) -> str:
+    if override:
+        if override not in orchestrator.agents:
+            raise SystemExit(
+                f"--source-agent {override!r} is not in the config "
+                f"(known: {sorted(orchestrator.agents)})"
+            )
+        return override
+    for agent in orchestrator.agents.values():
+        if agent.spec.active and not agent.spec.harmonizer:
+            return agent.spec.agent_name
+    for agent in orchestrator.agents.values():
+        if agent.spec.active:
+            return agent.spec.agent_name
+    raise SystemExit("No active agents found in config")
+
+
+def build_orchestrator(args: DemoArgs) -> tuple[FooOrchestrator, Path]:
+    config_path = resolve_config_path(args.config_path)
+    config = load_config(config_path)
+    ok, error = validate_runtime_agents(
+        config, config_path, allow_single_real=args.allow_single_real
+    )
+    if not ok:
+        print(error, file=sys.stderr)
+        raise SystemExit(2)
+    trace_store = TraceStore(config.settings.output_dir, config_snapshot=config.sanitized())
+    return FooOrchestrator(config=config, trace_store=trace_store), config_path
+
+
+def run_pipeline(orchestrator: FooOrchestrator, question: str, args: DemoArgs) -> int:
+    blob: dict[str, Any] = {}
+
+    print_section("FOO MCP Consensus Demo") if not args.json_only else None
+    if not args.json_only:
+        print(f"Run ID:   {orchestrator.run_id}")
+        print(f"Question: {question}")
+
+    broadcast = orchestrator.broadcast_message(question)
+    blob["broadcast"] = broadcast
+    if not args.json_only:
+        print_section("1. Broadcast")
+        for response in broadcast["data"]["responses"]:
+            print_response_row(response, args.max_chars)
+    if not broadcast["ok"]:
+        if args.json_only:
+            print(json.dumps(blob, indent=2))
+        return 10
+
+    source = pick_source_agent(orchestrator, args.source_agent)
+    blob["source_agent"] = source
+
+    vulnerability = orchestrator.run_vulnerability_analysis(source_agent_name=source)
+    blob["vulnerability"] = vulnerability
+    if not args.json_only:
+        print_section(f"2. Vulnerability Analysis (source = {source})")
+        critiques = vulnerability["data"].get("critiques", [])
+        if not critiques:
+            print("  (no peer critiques produced — only one non-harmonizer agent active?)")
+        for critique in critiques:
+            print_response_row(critique, args.max_chars)
+    if not vulnerability["ok"]:
+        if args.json_only:
+            print(json.dumps(blob, indent=2))
+        return 11
+
+    judgment = orchestrator.run_judgment_analysis(source_agent_name=source)
+    blob["judgment"] = judgment
+    if not args.json_only:
+        print_section(f"3. Harmonizer Judgment (consensus on {source})")
+        for j in judgment["data"].get("judgments", []):
+            print_full_response(j, args.max_chars * 4)
+    if not judgment["ok"]:
+        if args.json_only:
+            print(json.dumps(blob, indent=2))
+        return 12
+
+    reflection = orchestrator.run_reflection_analysis(target_agent_name=source)
+    blob["reflection"] = reflection
+    if not args.json_only:
+        print_section(f"4. Reflection (revised by {source})")
+        response = reflection["data"].get("response")
+        if response:
+            print_full_response(response, args.max_chars * 4)
+    if not reflection["ok"]:
+        if args.json_only:
+            print(json.dumps(blob, indent=2))
+        return 13
+
+    verify = orchestrator.verify_trace_chain()
+    blob["verify"] = verify
+    if not args.json_only:
+        print_section("5. Trace Chain Verification")
+        report = verify["data"]["verification"]
+        print(
+            f"  ok={report['ok']}  event_count={report['event_count']}  "
+            f"errors={len(report.get('errors', []))}"
+        )
+        if report.get("errors"):
+            for err in report["errors"][:5]:
+                print(f"    {err}")
+    if not verify["data"]["verification"]["ok"]:
+        if args.json_only:
+            print(json.dumps(blob, indent=2))
+        return 14
+
+    bundle = orchestrator.export_run_bundle(str(args.destination) if args.destination else None)
+    blob["bundle"] = bundle
+    if not args.json_only:
+        print_section("6. Bundle Export")
+        bdata = bundle["data"]
+        print(f"  run_id={bdata.get('run_id')}")
+        print(f"  bundle_path={bdata.get('bundle_path')}")
+    if not bundle["ok"]:
+        if args.json_only:
+            print(json.dumps(blob, indent=2))
+        return 15
+
+    if args.json_only:
+        print(json.dumps(blob, indent=2))
+    else:
+        print_section("Done")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> None:
+    load_dotenv_if_available()
+    args = parse_args(argv)
+    question = read_question(args)
+    orchestrator, _ = build_orchestrator(args)
+    rc = run_pipeline(orchestrator, question, args)
+    sys.exit(rc)
+
+
+if __name__ == "__main__":
+    main()