coppermind-cmo 0.1.0__py3-none-any.whl

coppermind_cmo/__init__.py

@@ -0,0 +1,3 @@
+"""Coppermind CMO — AI memory for fractional CMOs."""
+
+__version__ = "0.1.0"

coppermind_cmo/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point: python -m coppermind_cmo runs the MCP server."""
+
+from coppermind_cmo.server import main
+
+if __name__ == "__main__":
+    main()

coppermind_cmo/config.py

@@ -0,0 +1,82 @@
+"""Configuration from COPPERMIND_* environment variables.
+
+All numeric env vars are validated as integers at parse time (not on first use)
+per SERVER_SPEC.md startup requirements.
+
+Provider detection:
+  COPPERMIND_API_KEY set → hosted mode (gateway for LLM+embedding)
+  COPPERMIND_OLLAMA_HOST set → self-hosted LLM (Ollama)
+  COPPERMIND_EMBEDDING_HOST set → self-hosted embeddings (local server)
+  Neither → degraded mode (same as Sprint 1 when services are down)
+"""
+
+import os
+
+
+def _int_env(name: str, default: int) -> int:
+    val = os.environ.get(name)
+    if val is None:
+        return default
+    try:
+        return int(val)
+    except ValueError:
+        raise ValueError(f"{name} must be an integer, got: {val!r}")
+
+
+class Config:
+    """Parsed configuration from environment variables."""
+
+    def __init__(self):
+        # --- Hosted mode ---
+        self.api_key: str = os.environ.get("COPPERMIND_API_KEY", "")
+        self.gateway_url: str = os.environ.get(
+            "COPPERMIND_GATEWAY_URL",
+            "https://api.coppermind.app",
+        )
+
+        # --- Self-hosted PostgreSQL ---
+        self.pg_host: str = os.environ.get("COPPERMIND_PG_HOST", "localhost")
+        self.pg_port: int = _int_env("COPPERMIND_PG_PORT", 5432)
+        self.pg_db: str = os.environ.get("COPPERMIND_PG_DB", "coppermind_cmo")
+        self.pg_user: str = os.environ.get("COPPERMIND_PG_USER", "coppermind")
+        self.pg_password: str = os.environ.get("COPPERMIND_PG_PASSWORD", "")
+
+        # --- Self-hosted embedding service ---
+        self.embedding_host: str = os.environ.get("COPPERMIND_EMBEDDING_HOST", "localhost")
+        self.embedding_port: int = _int_env("COPPERMIND_EMBEDDING_PORT", 8400)
+
+        # --- Self-hosted Ollama ---
+        self.ollama_host: str = os.environ.get("COPPERMIND_OLLAMA_HOST", "localhost")
+        self.ollama_port: int = _int_env("COPPERMIND_OLLAMA_PORT", 11434)
+        self.ollama_model: str = os.environ.get("COPPERMIND_OLLAMA_MODEL", "gemma3:12b")
+
+        # --- Claude model configuration (hosted mode) ---
+        self.claude_fast_model: str = os.environ.get(
+            "COPPERMIND_CLAUDE_FAST_MODEL", "claude-haiku-4-5-20251001"
+        )
+        self.claude_synthesis_model: str = os.environ.get(
+            "COPPERMIND_CLAUDE_SYNTHESIS_MODEL", "claude-sonnet-4-20250514"
+        )
+
+        # --- Provider detection ---
+        if self.api_key:
+            self.llm_provider: str | None = "gateway"
+            self.embedding_provider: str | None = "gateway"
+            self.embedding_dims: int = 512
+            self.max_prompt_chars: int = 40000
+        else:
+            # Self-hosted: detect individually
+            has_ollama = bool(os.environ.get("COPPERMIND_OLLAMA_HOST"))
+            has_embedding = bool(os.environ.get("COPPERMIND_EMBEDDING_HOST"))
+            self.llm_provider = "ollama" if has_ollama else None
+            self.embedding_provider = "local" if has_embedding else None
+            self.embedding_dims = 384
+            self.max_prompt_chars = 13000
+
+    @property
+    def embedding_url(self) -> str:
+        return f"http://{self.embedding_host}:{self.embedding_port}"
+
+    @property
+    def ollama_url(self) -> str:
+        return f"http://{self.ollama_host}:{self.ollama_port}"

coppermind_cmo/db.py

@@ -0,0 +1,121 @@
+"""Database connection pool and query helpers.
+
+Adapted from old Coppermind lib/database.py. Simplified for CMO use case:
+- Single config source (COPPERMIND_PG_* env vars via Config)
+- psycopg2 ThreadedConnectionPool
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+from contextlib import contextmanager
+from typing import Any
+
+import psycopg2
+from psycopg2.pool import PoolError, ThreadedConnectionPool
+
+from coppermind_cmo.config import Config
+from coppermind_cmo.log import ToolLogger
+
+logger = ToolLogger("db")
+
+POOL_MIN = 1
+POOL_MAX = 10
+
+
+class Database:
+    """PostgreSQL connection pool wrapper."""
+
+    def __init__(self, config: Config):
+        self._config = config
+        self._pool: ThreadedConnectionPool | None = None
+        self._pool_lock = threading.Lock()
+
+    def _ensure_pool(self):
+        if self._pool is not None:
+            return
+        with self._pool_lock:
+            if self._pool is None:
+                ssl_kwargs = {}
+                if self._config.api_key:
+                    ca_path = os.path.join(
+                        os.path.dirname(__file__), "supabase-ca.pem"
+                    )
+                    ssl_kwargs = {
+                        "sslmode": "verify-ca",
+                        "sslrootcert": ca_path,
+                    }
+                self._pool = ThreadedConnectionPool(
+                    POOL_MIN, POOL_MAX,
+                    host=self._config.pg_host,
+                    port=self._config.pg_port,
+                    dbname=self._config.pg_db,
+                    user=self._config.pg_user,
+                    password=self._config.pg_password,
+                    connect_timeout=5,
+                    keepalives=1,
+                    keepalives_idle=30,
+                    keepalives_interval=10,
+                    keepalives_count=5,
+                    **ssl_kwargs,
+                )
+
+    @contextmanager
+    def connection(self):
+        """Borrow a connection from the pool. Auto-returned on exit."""
+        self._ensure_pool()
+        try:
+            conn = self._pool.getconn()
+        except PoolError:
+            logger.warn("Connection pool exhausted")
+            raise
+        _force_close = False
+        try:
+            yield conn
+        except Exception:
+            try:
+                conn.rollback()
+            except Exception:
+                _force_close = True  # rollback failed — connection is dead
+            raise
+        finally:
+            if conn.closed or _force_close:
+                self._pool.putconn(conn, close=True)
+            else:
+                self._pool.putconn(conn)
+
+    def fetch_all(self, sql: str, params: list[Any] | None = None) -> list[tuple]:
+        with self.connection() as conn:
+            with conn.cursor() as cur:
+                cur.execute(sql, params)
+                result = cur.fetchall()
+            conn.commit()
+            return result
+
+    def fetch_one(self, sql: str, params: list[Any] | None = None) -> tuple | None:
+        with self.connection() as conn:
+            with conn.cursor() as cur:
+                cur.execute(sql, params)
+                result = cur.fetchone()
+            conn.commit()
+            return result
+
+    def execute(self, sql: str, params: list[Any] | None = None):
+        with self.connection() as conn:
+            with conn.cursor() as cur:
+                cur.execute(sql, params)
+            conn.commit()
+
+    def execute_returning(self, sql: str, params: list[Any] | None = None) -> tuple | None:
+        with self.connection() as conn:
+            with conn.cursor() as cur:
+                cur.execute(sql, params)
+                row = cur.fetchone()
+            conn.commit()
+            return row
+
+    def close(self):
+        if self._pool is not None:
+            self._pool.closeall()
+            self._pool = None

coppermind_cmo/embedding_client.py

@@ -0,0 +1,120 @@
+"""HTTP client for embedding services.
+
+Supports two providers:
+  - Gateway (hosted): routes through Coppermind gateway → Voyage AI (512 dims)
+  - Local (self-hosted): sentence-transformers service on localhost:8400 (384 dims)
+
+Returns None on any failure — callers handle degraded mode.
+"""
+
+from typing import Optional
+
+import httpx
+
+from coppermind_cmo.config import Config
+from coppermind_cmo.log import ToolLogger
+
+logger = ToolLogger("embedding")
+
+# Legacy constant for backward compatibility in tests
+EXPECTED_DIMS = 384
+
+
+def _get_embedding_local(text: str, base_url: str, expected_dims: int, timeout: float = 10) -> Optional[list[float]]:
+    """Get embedding from the local sentence-transformers service."""
+    try:
+        resp = httpx.post(
+            f"{base_url.rstrip('/')}/embed",
+            json={"text": text},
+            timeout=timeout,
+        )
+        resp.raise_for_status()
+        embedding = resp.json()["embedding"]
+
+        if not isinstance(embedding, list) or len(embedding) == 0:
+            logger.warn("Invalid embedding shape: expected non-empty list")
+            return None
+        if not all(isinstance(x, (int, float)) for x in embedding):
+            logger.warn("Invalid embedding: contains non-numeric elements")
+            return None
+        if len(embedding) != expected_dims:
+            logger.warn(f"Embedding dimension mismatch: got {len(embedding)}, expected {expected_dims}")
+            return None
+
+        return embedding
+    except Exception as e:
+        logger.warn(f"Embedding request failed: {e}")
+        return None
+
+
+def _get_embedding_gateway(text: str, config: Config, timeout: float = 10) -> Optional[list[float]]:
+    """Get embedding from the Coppermind gateway → Voyage AI."""
+    try:
+        resp = httpx.post(
+            f"{config.gateway_url.rstrip('/')}/v1/embed",
+            json={"text": text},
+            headers={"Authorization": f"Bearer {config.api_key}"},
+            timeout=timeout,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        embedding = data["embedding"]
+
+        if not isinstance(embedding, list) or len(embedding) == 0:
+            logger.warn("Invalid gateway embedding shape: expected non-empty list")
+            return None
+        if not all(isinstance(x, (int, float)) for x in embedding):
+            logger.warn("Invalid gateway embedding: contains non-numeric elements")
+            return None
+        expected = data.get("dimensions", config.embedding_dims)
+        if len(embedding) != expected:
+            logger.warn(f"Gateway embedding dimension mismatch: got {len(embedding)}, expected {expected}")
+            return None
+
+        return embedding
+    except Exception as e:
+        logger.warn(f"Gateway embedding request failed: {e}")
+        return None
+
+
+def get_embedding(text: str, config: Config, timeout: float = 10) -> Optional[list[float]]:
+    """Get embedding vector for text. Routes to gateway or local based on config."""
+    if config.embedding_provider == "gateway":
+        return _get_embedding_gateway(text, config, timeout)
+    elif config.embedding_provider == "local":
+        return _get_embedding_local(text, config.embedding_url, config.embedding_dims, timeout)
+    else:
+        return None
+
+
+def check_health(config: Config, timeout: float = 5) -> bool:
+    """Check if the embedding service is healthy."""
+    if config.embedding_provider == "gateway":
+        try:
+            resp = httpx.get(
+                f"{config.gateway_url.rstrip('/')}/v1/health",
+                headers={"Authorization": f"Bearer {config.api_key}"},
+                timeout=timeout,
+            )
+            if resp.status_code != 200:
+                return False
+            return True
+        except Exception:
+            return False
+    elif config.embedding_provider == "local":
+        try:
+            resp = httpx.get(f"{config.embedding_url.rstrip('/')}/health", timeout=timeout)
+            if resp.status_code != 200:
+                return False
+            data = resp.json()
+            reported_dims = data.get("dimensions")
+            if reported_dims is not None and reported_dims != config.embedding_dims:
+                logger.warn(
+                    f"Embedding service dimension mismatch: reports {reported_dims}, expected {config.embedding_dims}"
+                )
+                return False
+            return True
+        except Exception:
+            return False
+    else:
+        return False

coppermind_cmo/embedding_server.py

@@ -0,0 +1,71 @@
+"""Standalone embedding HTTP server using sentence-transformers.
+
+Run: python -m coppermind_cmo.embedding_server
+Serves on port 8400 by default.
+"""
+
+import os
+import logging
+import threading
+
+from flask import Flask, request, jsonify
+
+logger = logging.getLogger(__name__)
+app = Flask(__name__)
+
+_model = None
+_model_lock = threading.Lock()
+MODEL_NAME = "all-MiniLM-L6-v2"
+DIMENSIONS = 384
+
+
+def _get_model():
+    global _model
+    if _model is not None:
+        return _model
+    with _model_lock:
+        if _model is None:
+            from sentence_transformers import SentenceTransformer
+            _model = SentenceTransformer(MODEL_NAME)
+            logger.info("Loaded embedding model: %s", MODEL_NAME)
+    return _model
+
+
+@app.route("/health")
+def health():
+    try:
+        _get_model()
+        return jsonify({"status": "ok", "model": MODEL_NAME, "dimensions": DIMENSIONS})
+    except Exception as e:
+        logger.error("Model load failed: %s", e)
+        return jsonify({"status": "error", "message": "Embedding model unavailable"}), 503
+
+
+@app.route("/embed", methods=["POST"])
+def embed():
+    data = request.get_json()
+    if not data or "text" not in data:
+        return jsonify({"error": "Missing 'text' field"}), 400
+
+    text = data["text"]
+    if not isinstance(text, str) or not text.strip():
+        return jsonify({"error": "'text' must be a non-empty string"}), 400
+    if len(text) > 50000:
+        return jsonify({"error": "Text exceeds 50,000 character limit"}), 400
+
+    model = _get_model()
+    embedding = model.encode(text, convert_to_numpy=True).tolist()
+    return jsonify({"embedding": embedding})
+
+
+def main():
+    port = int(os.environ.get("COPPERMIND_EMBEDDING_PORT", "8400"))
+    logger.info("Starting embedding server on port %d", port)
+    _get_model()  # Pre-load model
+    from waitress import serve
+    serve(app, host="127.0.0.1", port=port, threads=4)
+
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO)
+    main()

coppermind_cmo/errors.py

@@ -0,0 +1,44 @@
+"""Error response helpers per SERVER_SPEC.md error format."""
+
+from typing import Any
+
+
+def tool_error(code: str, message: str) -> dict[str, Any]:
+    return {"error": True, "code": code, "message": message}
+
+
+def NO_ACTIVE_MIND() -> dict[str, Any]:
+    return tool_error("NO_ACTIVE_MIND", "No active client. Call switch_client first.")
+
+
+def MIND_NOT_FOUND() -> dict[str, Any]:
+    return tool_error("MIND_NOT_FOUND", "Mind not found. Use list_minds to see available clients.")
+
+
+def MIND_ARCHIVED(name: str) -> dict[str, Any]:
+    return tool_error("MIND_ARCHIVED", f"Mind '{name}' is archived. Unarchive via direct DB access.")
+
+
+def INVALID_INPUT(message: str) -> dict[str, Any]:
+    return tool_error("INVALID_INPUT", message)
+
+
+def INVALID_MEMORY_TYPE(value: str) -> dict[str, Any]:
+    valid = "decision, preference, campaign_outcome, commitment, stakeholder, fact"
+    return tool_error("INVALID_MEMORY_TYPE", f"Invalid memory_type '{value}'. Valid types: {valid}")
+
+
+def INVALID_BRAND_DNA(message: str) -> dict[str, Any]:
+    return tool_error("INVALID_BRAND_DNA", message)
+
+
+def SERVICE_UNAVAILABLE(service: str) -> dict[str, Any]:
+    return tool_error("SERVICE_UNAVAILABLE", f"{service} is unreachable.")
+
+
+def MEMORY_NOT_FOUND(memory_id: str) -> dict[str, Any]:
+    return tool_error("MEMORY_NOT_FOUND", f"Memory '{memory_id}' not found or belongs to a different mind.")
+
+
+def INVALID_QUERY() -> dict[str, Any]:
+    return tool_error("INVALID_QUERY", "Query cannot be empty.")

coppermind_cmo/llm_client.py

@@ -0,0 +1,197 @@
+"""LLM client for classification and summarization.
+
+Supports two providers:
+  - Gateway (hosted): routes through Coppermind gateway → Claude API
+  - Ollama (self-hosted): direct Ollama HTTP API, 30s timeout, temperature=0
+
+The dispatcher function call_llm() routes to the correct provider based on config.
+"""
+
+import json
+import logging
+import urllib.request
+import urllib.error
+from typing import Optional
+
+import httpx
+
+from coppermind_cmo.config import Config
+
+logger = logging.getLogger(__name__)
+
+VALID_MEMORY_TYPES = {
+    "decision", "preference", "campaign_outcome",
+    "commitment", "stakeholder", "fact",
+}
+
+CLASSIFY_PROMPT = (
+    "Classify this client memory into exactly one type.\n\n"
+    "Types:\n"
+    '- decision: A choice that was made ("We\'re pausing LinkedIn ads")\n'
+    '- preference: A stated or implied preference ("Prefers casual brand voice")\n'
+    '- campaign_outcome: Results or metrics from a campaign ("Email open rate was 34%")\n'
+    '- commitment: An action item someone committed to ("Ben will send messaging by Friday")\n'
+    '- stakeholder: Information about a key person ("Sarah Chen is VP Marketing")\n'
+    "- fact: Any other noteworthy fact about the client\n\n"
+    "Examples:\n"
+    'Memory: "Pausing LinkedIn ads through Q2, reallocating to content marketing." \u2192 decision\n'
+    'Memory: "Sarah prefers async updates via Slack." \u2192 preference\n'
+    'Memory: "Q1 email: 34% open rate, curiosity gap won." \u2192 campaign_outcome\n'
+    'Memory: "Ben will send revised messaging by Friday." \u2192 commitment\n'
+    'Memory: "James Park is the new CEO, started January 2026." \u2192 stakeholder\n'
+    'Memory: "Series B, 45 employees, developer-first API platform." \u2192 fact\n\n'
+    "Return ONLY the type name, nothing else.\n\n"
+)
+
+SUMMARIZE_PROMPT = (
+    "Summarize this client memory in one sentence (max 100 chars). "
+    "Return ONLY the summary.\n\n"
+)
+
+
+# ---------------------------------------------------------------------------
+# Ollama provider (self-hosted)
+# ---------------------------------------------------------------------------
+
+def call_ollama(
+    prompt: str,
+    base_url: str,
+    model: str,
+    timeout: int = 30,
+) -> Optional[str]:
+    """Call Ollama API. Returns response text or None on failure."""
+    url = f"{base_url.rstrip('/')}/api/generate"
+    payload = json.dumps({
+        "model": model,
+        "prompt": prompt,
+        "stream": False,
+        "options": {"temperature": 0},
+    }).encode("utf-8")
+
+    req = urllib.request.Request(
+        url, data=payload,
+        headers={"Content-Type": "application/json"},
+    )
+
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+            return data.get("response", "")
+    except (urllib.error.URLError, urllib.error.HTTPError, TimeoutError, OSError) as e:
+        logger.warning("Ollama call failed: %s", e)
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Gateway provider (hosted)
+# ---------------------------------------------------------------------------
+
+def call_gateway_llm(
+    endpoint: str,
+    body: dict,
+    config: Config,
+    timeout: float = 30,
+) -> Optional[dict]:
+    """Call a gateway LLM endpoint. Returns parsed JSON response or None on failure."""
+    url = f"{config.gateway_url.rstrip('/')}/v1/{endpoint}"
+    try:
+        resp = httpx.post(
+            url,
+            json=body,
+            headers={"Authorization": f"Bearer {config.api_key}"},
+            timeout=timeout,
+        )
+        resp.raise_for_status()
+        return resp.json()
+    except Exception as e:
+        logger.warning("Gateway LLM call failed (%s): %s", endpoint, e)
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Dispatcher
+# ---------------------------------------------------------------------------
+
+def call_llm(
+    prompt: str,
+    config: Config,
+    use_synthesis_model: bool = False,
+) -> Optional[str]:
+    """Route LLM call to gateway or Ollama based on config.
+
+    Returns response text or None on failure.
+    """
+    if config.llm_provider == "gateway":
+        if use_synthesis_model:
+            result = call_gateway_llm("synthesize", {"prompt": prompt}, config)
+            if result is not None:
+                return result.get("text")
+        else:
+            # For classify/summarize, we send the raw prompt and let the gateway handle it
+            result = call_gateway_llm("synthesize", {"prompt": prompt}, config)
+            if result is not None:
+                return result.get("text")
+        return None
+    elif config.llm_provider == "ollama":
+        return call_ollama(prompt, config.ollama_url, config.ollama_model)
+    else:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# High-level functions
+# ---------------------------------------------------------------------------
+
+def classify_memory_type(content: str, config: Config) -> tuple[str, str]:
+    """Classify content into a memory type.
+
+    Returns (memory_type, classified_by) where classified_by is
+    'llm' or 'fallback'.
+    """
+    if config.llm_provider == "gateway":
+        result = call_gateway_llm("classify", {"content": content}, config)
+        if result is None:
+            return ("fact", "fallback")
+        memory_type = result.get("memory_type", "fact")
+        cleaned = memory_type.strip().lower().rstrip(".,;:!?").replace(" ", "_")
+        if cleaned in VALID_MEMORY_TYPES:
+            return (cleaned, "llm")
+        return ("fact", "llm")
+
+    # Ollama or no provider
+    prompt = CLASSIFY_PROMPT + f'Memory: "{content}"\nType:'
+
+    if config.llm_provider == "ollama":
+        response = call_ollama(prompt, config.ollama_url, config.ollama_model)
+    else:
+        response = None
+
+    if response is None:
+        return ("fact", "fallback")
+
+    cleaned = response.strip().lower().rstrip(".,;:!?").replace(" ", "_")
+    if cleaned in VALID_MEMORY_TYPES:
+        return (cleaned, "llm")
+    return ("fact", "llm")
+
+
+def summarize(content: str, config: Config) -> str:
+    """Generate a one-line summary. Falls back to truncation if LLM is down."""
+    if config.llm_provider == "gateway":
+        result = call_gateway_llm("summarize", {"content": content}, config)
+        if result is not None:
+            summary = result.get("summary", "")
+            return summary.strip()[:200]
+        return content[:100]
+
+    # Ollama or no provider
+    prompt = SUMMARIZE_PROMPT + f'Memory: "{content}"\nSummary:'
+
+    if config.llm_provider == "ollama":
+        response = call_ollama(prompt, config.ollama_url, config.ollama_model)
+    else:
+        response = None
+
+    if response is not None:
+        return response.strip()[:200]
+    return content[:100]