ocp-server 0.1.0__py3-none-any.whl

ocp_server/__init__.py

@@ -0,0 +1,2 @@
+"""OCP reference server."""
+__version__ = "0.1.0"

ocp_server/auth.py

@@ -0,0 +1,145 @@
+"""OCP authentication and workspace authorisation layer.
+
+Design
+------
+Auth is opt-in. If OCP_API_KEYS is unset the server runs in open/dev mode and
+every request is treated as fully-authorised. Set OCP_API_KEYS to enable.
+
+Environment variables
+---------------------
+OCP_API_KEYS
+    Comma-separated list of valid API keys that have access to ALL workspaces.
+    Example: OCP_API_KEYS=key-prod-abc123,key-ci-def456
+
+OCP_API_KEY_WORKSPACES
+    Semicolon-separated list of <key>:<ws_id1>,<ws_id2> pairs that restrict a
+    key to specific workspaces. Workspaces listed here override any entry in
+    OCP_API_KEYS for that key (OCP_API_KEY_WORKSPACES takes precedence).
+    Example: OCP_API_KEY_WORKSPACES=key-tenantA:ws_abc,ws_def;key-tenantB:ws_xyz
+
+Usage in stdio mode
+-------------------
+Set OCP_API_KEY=<key> in the environment before spawning ocp-server. The
+server reads OCP_API_KEY from the process environment during initialization.
+
+Usage in HTTP mode
+------------------
+Pass the key as a Bearer token:
+    Authorization: Bearer <key>
+
+The HTTP middleware extracts the token and stores it in the auth context var
+for the duration of that request.
+"""
+from __future__ import annotations
+
+import contextvars
+import os
+from dataclasses import dataclass, field
+
+
+# ------------------------------------------------------------------ #
+# Context variable — one AuthContext per asyncio task (= per request) #
+# ------------------------------------------------------------------ #
+
+_auth_ctx: contextvars.ContextVar["AuthContext"] = contextvars.ContextVar("ocp_auth_ctx")
+
+
+@dataclass(frozen=True)
+class AuthContext:
+    """Immutable auth state for one request / connection."""
+
+    api_key: str
+    # None means "all workspaces allowed"
+    allowed_workspaces: frozenset[str] | None = None
+    dev_mode: bool = False          # True when auth is disabled globally
+
+    def can_access_workspace(self, workspace_id: str) -> bool:
+        if self.dev_mode:
+            return True
+        if self.allowed_workspaces is None:
+            return True
+        return workspace_id in self.allowed_workspaces
+
+    def assert_workspace(self, workspace_id: str) -> None:
+        """Raise PermissionDeniedError if this context cannot access workspace_id."""
+        if not self.can_access_workspace(workspace_id):
+            raise PermissionDeniedError(
+                f"API key does not have access to workspace {workspace_id}"
+            )
+
+
+# Sentinel used when the server is in dev mode (no auth configured)
+_DEV_CONTEXT = AuthContext(api_key="__dev__", dev_mode=True)
+
+
+def get_auth_context() -> AuthContext:
+    """Return the AuthContext for the current request.
+
+    Falls back to the dev context if none has been set (should only happen in
+    test code that bypasses the server wiring).
+    """
+    return _auth_ctx.get(_DEV_CONTEXT)
+
+
+def set_auth_context(ctx: AuthContext) -> contextvars.Token:
+    return _auth_ctx.set(ctx)
+
+
+def reset_auth_context(token: contextvars.Token) -> None:
+    _auth_ctx.reset(token)
+
+
+# ------------------------------------------------------------------ #
+# Auth config                                                          #
+# ------------------------------------------------------------------ #
+
+@dataclass
+class AuthConfig:
+    """Parsed auth configuration derived from environment variables."""
+
+    # key → frozenset of workspace IDs, or None for unrestricted
+    key_map: dict[str, frozenset[str] | None] = field(default_factory=dict)
+    enabled: bool = False
+
+    def validate_key(self, key: str) -> AuthContext | None:
+        """Return an AuthContext for a valid key, or None if the key is invalid."""
+        if not self.enabled:
+            return _DEV_CONTEXT
+        if key not in self.key_map:
+            return None
+        return AuthContext(api_key=key, allowed_workspaces=self.key_map[key])
+
+
+def load_auth_config() -> AuthConfig:
+    """Build AuthConfig from environment variables."""
+    cfg = AuthConfig()
+
+    raw_keys = os.environ.get("OCP_API_KEYS", "").strip()
+    for k in (k.strip() for k in raw_keys.split(",") if k.strip()):
+        cfg.key_map[k] = None   # unrestricted
+        cfg.enabled = True
+
+    raw_scoped = os.environ.get("OCP_API_KEY_WORKSPACES", "").strip()
+    for entry in (e.strip() for e in raw_scoped.split(";") if e.strip()):
+        if ":" not in entry:
+            continue
+        key, workspaces_str = entry.split(":", 1)
+        key = key.strip()
+        ws = frozenset(w.strip() for w in workspaces_str.split(",") if w.strip())
+        cfg.key_map[key] = ws
+        cfg.enabled = True
+
+    return cfg
+
+
+# ------------------------------------------------------------------ #
+# Errors                                                               #
+# ------------------------------------------------------------------ #
+
+class PermissionDeniedError(Exception):
+    code = "PERMISSION_DENIED"
+
+
+class UnauthorisedError(Exception):
+    """Raised at the transport level when no valid key is presented."""
+    code = "UNAUTHORISED"

ocp_server/embedder.py

@@ -0,0 +1,169 @@
+"""Embedding backends for OCP.
+
+Default: HashEmbedder — pure numpy, zero dependencies, works on any platform/Python.
+Optional backends (set OCP_EMBEDDER env var):
+  - "hash"      HashEmbedder (default)
+  - "fastembed" FastEmbedEmbedder (requires: pip install fastembed)
+  - "openai"    OpenAIEmbedder    (requires: pip install openai, OPENAI_API_KEY set)
+"""
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import os
+import re
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class EmbedderProtocol(Protocol):
+    async def embed(self, text: str) -> list[float]: ...
+    @property
+    def dim(self) -> int: ...
+
+
+# ------------------------------------------------------------------ #
+# Hash n-gram embedder (built-in, no extra deps)                      #
+# ------------------------------------------------------------------ #
+
+class HashEmbedder:
+    """
+    Locality-sensitive hash embedding via character n-grams.
+
+    Splits text into overlapping 3-grams, hashes each into one of `dim`
+    buckets, and returns an L2-normalised count vector.  Fast, deterministic,
+    works on Python 3.13 + Intel Mac with only numpy.
+    """
+
+    def __init__(self, dim: int = 512) -> None:
+        self._dim = dim
+
+    @property
+    def dim(self) -> int:
+        return self._dim
+
+    async def embed(self, text: str) -> list[float]:
+        return self._embed_sync(text)
+
+    def _embed_sync(self, text: str) -> list[float]:
+        import numpy as np
+
+        text = re.sub(r"\s+", " ", text.lower()).strip()
+        vec = np.zeros(self._dim, dtype=np.float32)
+
+        # Character 3-grams
+        for i in range(len(text) - 2):
+            gram = text[i : i + 3]
+            bucket = int(hashlib.md5(gram.encode()).hexdigest(), 16) % self._dim
+            vec[bucket] += 1.0
+
+        # Word unigrams (extra signal for exact-keyword matches)
+        for word in text.split():
+            bucket = int(hashlib.md5(word.encode()).hexdigest(), 16) % self._dim
+            vec[bucket] += 2.0
+
+        norm = np.linalg.norm(vec)
+        if norm > 0:
+            vec /= norm
+        return vec.tolist()
+
+
+# ------------------------------------------------------------------ #
+# fastembed backend (optional)                                         #
+# ------------------------------------------------------------------ #
+
+class FastEmbedEmbedder:
+    """Uses fastembed (BAAI/bge-small-en-v1.5 by default)."""
+
+    def __init__(self, model_name: str = "BAAI/bge-small-en-v1.5") -> None:
+        self._model_name = model_name
+        self._model: Any = None
+        self._dim_val: int | None = None
+
+    @property
+    def dim(self) -> int:
+        return self._dim_val or 384
+
+    def _load(self) -> None:
+        if self._model is None:
+            from fastembed import TextEmbedding
+            self._model = TextEmbedding(model_name=self._model_name)
+
+    async def embed(self, text: str) -> list[float]:
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(None, self._embed_sync, text)
+
+    def _embed_sync(self, text: str) -> list[float]:
+        self._load()
+        result = list(self._model.embed([text]))
+        vec = result[0].tolist()
+        self._dim_val = len(vec)
+        return vec
+
+
+# ------------------------------------------------------------------ #
+# OpenAI backend (optional)                                            #
+# ------------------------------------------------------------------ #
+
+class OpenAIEmbedder:
+    """Uses the OpenAI embeddings API (text-embedding-3-small)."""
+
+    def __init__(self, model: str = "text-embedding-3-small") -> None:
+        self._model = model
+
+    @property
+    def dim(self) -> int:
+        return 1536
+
+    async def embed(self, text: str) -> list[float]:
+        import openai
+        client = openai.AsyncOpenAI()
+        resp = await client.embeddings.create(input=text, model=self._model)
+        return resp.data[0].embedding
+
+
+# ------------------------------------------------------------------ #
+# Factory                                                              #
+# ------------------------------------------------------------------ #
+
+def make_embedder() -> EmbedderProtocol:
+    backend = os.environ.get("OCP_EMBEDDER", "hash").lower()
+    if backend == "fastembed":
+        model = os.environ.get("OCP_EMBED_MODEL", "BAAI/bge-small-en-v1.5")
+        return FastEmbedEmbedder(model)
+    if backend == "openai":
+        model = os.environ.get("OCP_EMBED_MODEL", "text-embedding-3-small")
+        return OpenAIEmbedder(model)
+    return HashEmbedder(dim=int(os.environ.get("OCP_EMBED_DIM", "512")))
+
+
+# Convenience alias used by server.py
+Embedder = HashEmbedder
+
+
+# ------------------------------------------------------------------ #
+# Tokenizer                                                            #
+# ------------------------------------------------------------------ #
+
+class Tokenizer:
+    """Token counter.  Uses tiktoken when available, falls back to word-split."""
+
+    def __init__(self) -> None:
+        self._enc: Any = None
+        self._use_tiktoken = True
+
+    def _load(self) -> None:
+        if self._enc is not None or not self._use_tiktoken:
+            return
+        try:
+            import tiktoken
+            self._enc = tiktoken.get_encoding("cl100k_base")
+        except ImportError:
+            self._use_tiktoken = False
+
+    def count(self, text: str) -> int:
+        self._load()
+        if self._enc:
+            return len(self._enc.encode(text))
+        # Fallback: ~4 chars per token heuristic
+        return max(1, len(text) // 4)

ocp_server/indexer.py

@@ -0,0 +1,158 @@
+"""File-system workspace indexer.
+
+Changes:
+  §6.1 trigger 3 — detect hash-mismatch on reindex: stale old chunks and return
+                   their IDs so the caller can emit chunk.invalidated.
+  §7.2            — accepts optional progress_cb for index.progress events.
+"""
+from __future__ import annotations
+
+import hashlib
+import time
+from pathlib import Path
+from typing import Awaitable, Callable
+
+from ocp_server.embedder import EmbedderProtocol as Embedder
+from ocp_server.models import Chunk, ChunkSource, SourceRange, make_chunk_id
+from ocp_server.storage.base import BaseStore
+
+_TEXT_EXTENSIONS = {
+    ".py", ".ts", ".tsx", ".js", ".jsx", ".go", ".rs", ".java", ".kt",
+    ".rb", ".cpp", ".c", ".h", ".cs", ".swift", ".md", ".txt", ".yaml",
+    ".yml", ".json", ".toml", ".html", ".css", ".sh", ".sql",
+}
+_MAX_CHUNK_BYTES = 4096
+
+# Type alias: receives (progress 0..1) and returns None
+ProgressCallback = Callable[[float], Awaitable[None]]
+
+
+async def index_workspace(
+    store: BaseStore,
+    embedder: Embedder,
+    workspace_id: str,
+    root_uri: str,
+    paths: list[str] | None,
+    progress_cb: ProgressCallback | None = None,
+) -> tuple[dict, list[str]]:
+    """Index files in the workspace.
+
+    Returns (result_dict, stale_chunk_ids).
+    stale_chunk_ids contains IDs of previously-active chunks whose content_hash
+    changed during this reindex (§6.1 trigger 3).
+    """
+    root = root_uri.removeprefix("file://")
+    root_path = Path(root)
+
+    if not root_path.exists():
+        return {"indexed": 0, "skipped": 0, "duration_ms": 0}, []
+
+    t0 = time.monotonic()
+
+    if paths:
+        targets = [root_path / p.lstrip("/") for p in paths]
+    else:
+        targets = [root_path]
+
+    # Collect all candidate files first so we can report progress
+    all_files: list[Path] = []
+    for target in targets:
+        if target.is_file():
+            all_files.append(target)
+        else:
+            all_files.extend(p for p in target.rglob("*") if p.is_file())
+
+    total = len(all_files)
+    indexed = 0
+    skipped = 0
+    stale_ids: list[str] = []
+
+    for i, file_path in enumerate(all_files):
+        if file_path.suffix.lower() not in _TEXT_EXTENSIONS:
+            skipped += 1
+        else:
+            try:
+                text = file_path.read_text(encoding="utf-8", errors="ignore")
+            except OSError:
+                skipped += 1
+            else:
+                uri = f"file://{file_path.resolve()}"
+
+                # §6.1 trigger 3: snapshot active chunk IDs before reindexing this file
+                prior_ids = await store.get_active_chunk_ids_for_uri(workspace_id, uri)
+                prior_set = set(prior_ids)
+
+                new_chunks = _chunk_file(workspace_id, file_path, root_path, text)
+                new_ids: set[str] = set()
+                for chunk in new_chunks:
+                    embedding = await embedder.embed(chunk.content)
+                    await store.upsert_chunk(chunk, embedding)
+                    new_ids.add(chunk.id)
+                    indexed += 1
+
+                # Any prior active chunk not in the new set has a changed hash
+                outdated = prior_set - new_ids
+                if outdated:
+                    await store.mark_chunks_stale(list(outdated))
+                    stale_ids.extend(outdated)
+
+        # Emit progress (§7.2 index.progress)
+        if progress_cb and total > 0:
+            await progress_cb((i + 1) / total)
+
+    duration_ms = int((time.monotonic() - t0) * 1000)
+    return {"indexed": indexed, "skipped": skipped, "duration_ms": duration_ms}, stale_ids
+
+
+def _chunk_file(workspace_id: str, file_path: Path, root: Path, text: str) -> list[Chunk]:
+    # R1: absolute resolved URI — matches invalidation LIKE-patterns (includes symlink resolution)
+    uri = f"file://{file_path.resolve()}"
+
+    lines = text.splitlines(keepends=True)
+    chunks: list[Chunk] = []
+    start_line = 0
+    ext = file_path.suffix.lstrip(".")
+    lang_map = {
+        "py": "python", "ts": "typescript", "tsx": "typescript",
+        "js": "javascript", "jsx": "javascript", "go": "go",
+        "rs": "rust", "java": "java", "rb": "ruby", "md": "markdown",
+    }
+    language = lang_map.get(ext)
+
+    while start_line < len(lines):
+        buf = ""
+        end_line = start_line
+        while end_line < len(lines) and len((buf + lines[end_line]).encode()) < _MAX_CHUNK_BYTES:
+            buf += lines[end_line]
+            end_line += 1
+        if not buf.strip():
+            start_line = end_line + 1
+            continue
+
+        content_hash = hashlib.sha256(buf.encode()).hexdigest()
+        range_repr = f"{start_line}:{end_line}"
+        chunk_id = make_chunk_id(workspace_id, uri, range_repr, content_hash)
+
+        start_byte = sum(len(ln.encode()) for ln in lines[:start_line])
+        end_byte = start_byte + len(buf.encode())
+
+        chunks.append(Chunk(
+            id=chunk_id,
+            workspace_id=workspace_id,
+            source=ChunkSource(
+                uri=uri,
+                range=SourceRange(
+                    start_line=start_line,
+                    end_line=end_line - 1,
+                    start_byte=start_byte,
+                    end_byte=end_byte,
+                ),
+                content_hash=content_hash,
+            ),
+            kind="section",
+            language=language,
+            content=buf,
+        ))
+        start_line = end_line
+
+    return chunks

ocp_server/models.py

@@ -0,0 +1,110 @@
+"""OCP core data model — §3."""
+from __future__ import annotations
+
+import base64
+import hashlib
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class Scope(str, Enum):
+    agent = "agent"
+    session = "session"
+    global_ = "global"
+
+    @classmethod
+    def _missing_(cls, value: object) -> "Scope | None":
+        if value == "global":
+            return cls.global_
+        return None
+
+
+class ConformanceLevel(str, Enum):
+    core = "core"
+    core_coordination = "core+coordination"
+    full = "full"
+
+
+class SourceRange(BaseModel):
+    start_byte: int | None = None
+    end_byte: int | None = None
+    start_line: int | None = None
+    end_line: int | None = None
+
+
+class ChunkSource(BaseModel):
+    uri: str
+    range: SourceRange | None = None
+    content_hash: str
+
+
+class Chunk(BaseModel):
+    id: str
+    workspace_id: str
+    source: ChunkSource
+    kind: str
+    language: str | None = None
+    symbol: str | None = None
+    content: str
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    version: int = 1
+
+
+_MAX_KEY_BYTES = 256
+_MAX_VALUE_BYTES = 1 * 1024 * 1024  # 1 MiB
+
+
+class StateEntry(BaseModel):
+    key: str
+    value: Any
+    scope: Scope
+    workspace_id: str | None = None
+    session_id: str | None = None
+    agent_id: str | None = None
+    ttl_seconds: int | None = None
+    updated_at: str | None = None
+    version: int = 1
+
+    @model_validator(mode="after")
+    def _check_scope_ids(self) -> "StateEntry":
+        if self.scope == Scope.agent and not self.agent_id:
+            raise ValueError("agent_id required for agent scope")
+        if self.scope == Scope.session and not self.session_id:
+            raise ValueError("session_id required for session scope")
+        if self.scope in (Scope.session, Scope.global_) and not self.workspace_id:
+            raise ValueError("workspace_id required for session/global scope")
+        # §3.2 — key: max 256 bytes; value: max 1 MiB
+        if len(self.key.encode()) > _MAX_KEY_BYTES:
+            raise ValueError(f"key exceeds {_MAX_KEY_BYTES} bytes")
+        import json as _json
+        try:
+            encoded = _json.dumps(self.value).encode()
+        except (TypeError, ValueError) as exc:
+            raise ValueError(f"value is not JSON-serialisable: {exc}") from exc
+        if len(encoded) > _MAX_VALUE_BYTES:
+            raise ValueError(f"value exceeds {_MAX_VALUE_BYTES} bytes (1 MiB)")
+        return self
+
+
+class EventEnvelope(BaseModel):
+    type: str
+    event_id: str
+    timestamp: str
+    workspace_id: str
+    subscription_id: str
+    payload: dict[str, Any] = Field(default_factory=dict)
+
+
+# §3.4 — deterministic chunk ID
+def make_chunk_id(workspace_id: str, uri: str, range_repr: str, content_hash: str) -> str:
+    raw = f"{workspace_id}\x00{uri}\x00{range_repr}\x00{content_hash}".encode()
+    digest = hashlib.sha256(raw).digest()
+    return base64.b32encode(digest).decode().lower()[:24]
+
+
+# §3.3 — deterministic workspace ID
+def make_workspace_id(root_uri: str) -> str:
+    digest = hashlib.sha256(root_uri.encode()).hexdigest()
+    return f"ws_{digest[:16]}"