opencontextengine-client 0.1.0__py3-none-any.whl

oce_client/models.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class FileStatus(str, Enum):
+    PRESENT = "present"
+    SKIPPED = "skipped"
+    DELETED = "deleted"
+
+
+class BlobStatus(str, Enum):
+    LOCAL = "local"
+    UPLOADED = "uploaded"
+    READY = "ready"
+    FAILED = "failed"
+
+
+@dataclass(frozen=True)
+class FileRecord:
+    path: str
+    blob_name: str | None
+    status: FileStatus
+    content: str | None = None
+    size: int = 0
+    mtime_ns: int | None = None
+    source: str = "filesystem"
+    generation: int = 0
+    committed_blob_name: str | None = None
+
+
+@dataclass(frozen=True)
+class BlobUpload:
+    path: str
+    content: str
+    blob_name: str
+
+
+@dataclass(frozen=True)
+class BlobDelta:
+    checkpoint_id: str | None
+    added_blobs: tuple[str, ...] = ()
+    deleted_blobs: tuple[str, ...] = ()
+
+    def to_api_dict(self) -> dict[str, object]:
+        return {
+            "checkpoint_id": self.checkpoint_id or "",
+            "added_blobs": list(self.added_blobs),
+            "deleted_blobs": list(self.deleted_blobs),
+        }
+
+
+@dataclass(frozen=True)
+class UploadPlan:
+    uploads: tuple[BlobUpload, ...]
+    delta: BlobDelta
+    skipped_paths: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class UploadResult:
+    blob_names: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class MissingResult:
+    unknown_blob_names: tuple[str, ...] = ()
+    nonindexed_blob_names: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class BlobStatusResult:
+    unknown_blob_names: tuple[str, ...] = ()
+    nonindexed_blob_names: tuple[str, ...] = ()
+    checkpoint_not_found: bool = False
+
+
+@dataclass(frozen=True)
+class CheckpointResult:
+    new_checkpoint_id: str
+
+
+@dataclass(frozen=True)
+class RetrievalResult:
+    formatted_retrieval: str
+    elapsed_ms: int = 0
+
+
+@dataclass(frozen=True)
+class SyncResult:
+    uploaded_blob_names: tuple[str, ...]
+    checkpoint_id: str | None
+    added_blobs: tuple[str, ...]
+    deleted_blobs: tuple[str, ...]
+
+
+@dataclass
+class WorkspaceSnapshot:
+    files: dict[str, FileRecord] = field(default_factory=dict)
+    checkpoint_id: str | None = None
+    generation: int = 0

oce_client/ports.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from pathlib import Path
+from collections.abc import Callable
+from typing import Protocol, Sequence
+
+from .models import (
+    BlobStatusResult,
+    BlobUpload,
+    CheckpointResult,
+    MissingResult,
+    RetrievalResult,
+    UploadResult,
+)
+
+
+class BlobIdentity(Protocol):
+    def calculate(self, path: str, content: str) -> str: ...
+
+
+class BlobApi(Protocol):
+    def find_missing(self, blob_names: Sequence[str]) -> MissingResult: ...
+
+    def batch_upload(self, blobs: Sequence[BlobUpload]) -> UploadResult: ...
+
+    def blob_status(
+        self, blob_names: Sequence[str], checkpoint_id: str | None = None
+    ) -> BlobStatusResult: ...
+
+    def checkpoint(
+        self,
+        checkpoint_id: str | None,
+        added_blobs: Sequence[str],
+        deleted_blobs: Sequence[str],
+    ) -> CheckpointResult: ...
+
+    def retrieve(
+        self,
+        query: str,
+        checkpoint_id: str | None,
+        added_blobs: Sequence[str],
+        deleted_blobs: Sequence[str],
+    ) -> RetrievalResult: ...
+
+
+class StateStore(Protocol):
+    def load_snapshot(self): ...
+
+
+class WatchHandle(Protocol):
+    def stop(self) -> None: ...
+
+    def join(self, timeout: float | None = None) -> None: ...
+
+
+class FileSource(Protocol):
+    def scan(self, root: Path, matcher: IgnoreMatcher) -> dict[str, str]: ...
+
+    def read(self, path: Path) -> str: ...
+
+
+class IgnoreMatcher(Protocol):
+    def ignores(self, path: str, *, is_dir: bool = False) -> bool: ...
+
+
+class Watcher(Protocol):
+    def start(self, callback: Callable[[], None]) -> WatchHandle: ...

oce_client/runtime.py

@@ -0,0 +1,245 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from collections.abc import Iterable, Sequence
+
+from .context import WorkspaceContext
+from .defaults import DEFAULT_API_KEY, DEFAULT_API_URL
+from .http import OceHttpClient
+
+
+class ClientConfigurationError(ValueError):
+    """Raised when a CLI/MCP runtime cannot be configured safely."""
+
+
+@dataclass(frozen=True)
+class ClientSettings:
+    root: Path
+    api_url: str
+    api_key: str
+    state_path: Path | None = None
+    runtime_patterns: tuple[str, ...] = ()
+
+    @classmethod
+    def from_environment(
+        cls,
+        *,
+        root: str | os.PathLike[str] | None = None,
+        api_url: str | None = None,
+        api_key: str | None = None,
+        state_path: str | os.PathLike[str] | None = None,
+        runtime_patterns: Iterable[str] | None = None,
+        require_api_key: bool = True,
+    ) -> "ClientSettings":
+        resolved_root = Path(
+            root if root is not None else os.environ.get("OCE_WORKSPACE", ".")
+        ).expanduser().resolve()
+        resolved_url = (
+            api_url if api_url is not None else os.environ.get("OCE_API_URL", DEFAULT_API_URL)
+        ).strip()
+        resolved_key = api_key if api_key is not None else os.environ.get(
+            "OCE_API_KEY", DEFAULT_API_KEY
+        )
+        resolved_state = _resolve_path_option(state_path, "OCE_STATE_PATH")
+        if not resolved_url:
+            raise ClientConfigurationError("OCE API URL must not be empty")
+        if require_api_key and not resolved_key:
+            raise ClientConfigurationError(
+                "OCE API key is required; set OCE_API_KEY"
+            )
+        return cls(
+            root=resolved_root,
+            api_url=resolved_url.rstrip("/"),
+            api_key=resolved_key,
+            state_path=resolved_state,
+            runtime_patterns=tuple(
+                runtime_patterns
+                if runtime_patterns is not None
+                else iter_runtime_patterns((os.environ.get("OCE_IGNORE", ""),))
+            ),
+        )
+
+
+@dataclass(frozen=True)
+class McpConfiguration:
+    """Fully resolved configuration for the long-running MCP process."""
+
+    client: ClientSettings
+    workspace_roots: tuple[Path, ...]
+    state_dir: Path | None
+    debounce_ms: int
+    initial_sync: str
+    ready_timeout: float
+    log_level: str
+
+    @classmethod
+    def from_environment(
+        cls,
+        *,
+        workspace_roots: Sequence[str | os.PathLike[str]] | None = None,
+        api_url: str | None = None,
+        state_path: str | os.PathLike[str] | None = None,
+        state_dir: str | os.PathLike[str] | None = None,
+        runtime_patterns: Iterable[str] | None = None,
+        debounce_ms: int | None = None,
+        initial_sync: str | None = None,
+        ready_timeout: float | None = None,
+        log_level: str | None = None,
+    ) -> "McpConfiguration":
+        roots = _resolve_mcp_roots(workspace_roots)
+        if not roots:
+            raise ClientConfigurationError(
+                "MCP requires at least one workspace; pass --workspace or set "
+                "OCE_WORKSPACE/OCE_WORKSPACES"
+            )
+
+        resolved_state_dir = _resolve_path_option(state_dir, "OCE_STATE_DIR")
+        client = ClientSettings.from_environment(
+            root=roots[0],
+            api_url=api_url,
+            state_path=state_path,
+            runtime_patterns=runtime_patterns,
+            require_api_key=True,
+        )
+        if client.state_path is not None and resolved_state_dir is not None:
+            raise ClientConfigurationError(
+                "MCP state configuration is ambiguous; choose OCE_STATE_PATH/--state-path "
+                "or OCE_STATE_DIR/--state-dir"
+            )
+        if len(roots) > 1 and client.state_path is not None and resolved_state_dir is None:
+            raise ClientConfigurationError(
+                "multiple MCP workspaces cannot share OCE_STATE_PATH; use --state-dir "
+                "or OCE_STATE_DIR"
+            )
+
+        resolved_debounce = _resolve_int_option(
+            debounce_ms, "OCE_DEBOUNCE_MS", 500
+        )
+        if resolved_debounce < 0:
+            raise ClientConfigurationError("debounce-ms must not be negative")
+        resolved_initial = (
+            initial_sync
+            if initial_sync is not None
+            else os.environ.get("OCE_INITIAL_SYNC", "background")
+        ).strip().lower()
+        if resolved_initial not in {"background", "blocking", "off"}:
+            raise ClientConfigurationError(
+                "initial-sync must be one of: background, blocking, off"
+            )
+        resolved_timeout = _resolve_float_option(
+            ready_timeout, "OCE_READY_TIMEOUT", 3.0
+        )
+        if resolved_timeout < 0:
+            raise ClientConfigurationError("ready-timeout must not be negative")
+        resolved_log_level = (
+            log_level
+            if log_level is not None
+            else os.environ.get("OCE_LOG_LEVEL", "warning")
+        ).strip().lower()
+        if resolved_log_level not in {"debug", "info", "warning", "error", "critical"}:
+            raise ClientConfigurationError(
+                "log-level must be one of: debug, info, warning, error, critical"
+            )
+        return cls(
+            client=client,
+            workspace_roots=roots,
+            state_dir=resolved_state_dir,
+            debounce_ms=resolved_debounce,
+            initial_sync=resolved_initial,
+            ready_timeout=resolved_timeout,
+            log_level=resolved_log_level,
+        )
+
+
+class ClientRuntime:
+    """Lazy, closeable context shared by one CLI command or MCP process."""
+
+    def __init__(self, settings: ClientSettings) -> None:
+        self.settings = settings
+        self._context: WorkspaceContext | None = None
+
+    def context(self) -> WorkspaceContext:
+        if self._context is None:
+            if not self.settings.root.is_dir():
+                raise ClientConfigurationError(
+                    f"workspace is not a directory: {self.settings.root}"
+                )
+            api = OceHttpClient(self.settings.api_url, self.settings.api_key)
+            try:
+                self._context = WorkspaceContext.open(
+                    self.settings.root,
+                    api,
+                    state_path=self.settings.state_path,
+                    runtime_patterns=self.settings.runtime_patterns,
+                )
+            except Exception:
+                api.close()
+                raise
+        return self._context
+
+    def close(self) -> None:
+        if self._context is not None:
+            self._context.close()
+            self._context = None
+
+    def __enter__(self) -> "ClientRuntime":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+def iter_runtime_patterns(values: Iterable[str]) -> tuple[str, ...]:
+    patterns: list[str] = []
+    for value in values:
+        for comma_group in value.replace("\r", "\n").split(","):
+            patterns.extend(
+                line.strip() for line in comma_group.splitlines() if line.strip()
+            )
+    return tuple(patterns)
+
+
+def _resolve_path_option(
+    value: str | os.PathLike[str] | None,
+    environment_name: str,
+) -> Path | None:
+    raw = value if value is not None else os.environ.get(environment_name)
+    return None if raw is None or not str(raw).strip() else Path(raw).expanduser().resolve()
+
+
+def _resolve_mcp_roots(
+    values: Sequence[str | os.PathLike[str]] | None,
+) -> tuple[Path, ...]:
+    if values is None:
+        raw_values: Sequence[str | os.PathLike[str]]
+        configured = os.environ.get("OCE_WORKSPACES")
+        if configured:
+            raw_values = tuple(part for part in configured.split(os.pathsep) if part)
+        else:
+            single = os.environ.get("OCE_WORKSPACE")
+            raw_values = () if single is None or not single.strip() else (single,)
+    else:
+        raw_values = values
+    return tuple(dict.fromkeys(Path(value).expanduser().resolve() for value in raw_values))
+
+
+def _resolve_int_option(value: int | None, environment_name: str, default: int) -> int:
+    raw = value if value is not None else os.environ.get(environment_name)
+    if raw is None:
+        return default
+    try:
+        return int(raw)
+    except (TypeError, ValueError) as exc:
+        raise ClientConfigurationError(f"{environment_name} must be an integer") from exc
+
+
+def _resolve_float_option(value: float | None, environment_name: str, default: float) -> float:
+    raw = value if value is not None else os.environ.get(environment_name)
+    if raw is None:
+        return default
+    try:
+        return float(raw)
+    except (TypeError, ValueError) as exc:
+        raise ClientConfigurationError(f"{environment_name} must be a number") from exc

oce_client/skill/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: oce-client
+description: "Use the oce-client CLI to synchronize one local workspace and retrieve current code context from OpenContextEngine."
+---
+
+# OpenContextEngine CLI
+
+This skill documents the `oce-client` command-line interface for an AI agent.
+It is a CLI workflow: invoke a command, read its result, and continue the task.
+
+## 1. Command Reference
+
+### Version and package identity
+
+- Distribution package: `opencontextengine-client`
+- Python package: `oce_client`
+- CLI executable: `oce-client`
+- Check the installed CLI version with `oce-client --version`.
+
+### Global options
+
+Global options must appear before the subcommand:
+
+```text
+oce-client --root <workspace> --api-url <url> --state-path <file> <command>
+```
+
+- `--root`: workspace directory; otherwise use `OCE_WORKSPACE`, then the
+  current directory.
+- `--api-url`: service URL; otherwise use `OCE_API_URL`, then
+  `http://127.0.0.1:8986`.
+- `--state-path`: SQLite state file; otherwise use `OCE_STATE_PATH`, then
+  `<workspace>/.oce-client/state.sqlite3`.
+- `--ignore PATTERN`: add a runtime ignore pattern; repeat it when needed.
+
+The API key has no CLI option. Load it through `OCE_API_KEY`; the local default
+is `sk-opencontextengine`.
+
+### Workspace commands
+
+```text
+oce-client --root <workspace> sync [--json]
+oce-client --root <workspace> status [--json]
+oce-client --root <workspace> retrieve [--scope workspace|working_set] [--json] <query>
+oce-client --root <workspace> observe <path> [--content <text> | --file <file>] [--json]
+oce-client --root <workspace> remove <path> [--json]
+oce-client --root <workspace> watch [--debounce-ms <milliseconds>]
+oce-client skill path [--json]
+oce-client skill install [--target <directory>] [--force] [--json]
+```
+
+- `sync` scans the workspace, uploads new or changed blobs, and commits a new
+  server checkpoint. This is the command that makes retrieval reflect the
+  current files.
+- `status` reads only the local SQLite inventory and checkpoint. It does not
+  contact the service and does not require an API key.
+- `retrieve` sends a natural-language code question to the service using the
+  last local checkpoint. Use `--scope` only when the task requires the
+  corresponding retrieval scope.
+- `observe` stages explicit editor content in the local state. It does not
+  publish the content until `sync` runs.
+- `remove` stages a workspace-relative deletion. It also requires `sync` to
+  publish the change.
+- `watch` keeps a foreground process alive and incrementally syncs filesystem
+  changes. Run an initial successful `sync` before starting it.
+
+`skill path` and `skill install` are installation maintenance commands; they
+are not part of normal code retrieval.
+
+## 2. Workflow
+
+### One-shot retrieval
+
+Use this workflow when no long-running watcher is already maintaining the
+workspace:
+
+```text
+1. Set OCE_WORKSPACE, OCE_API_URL, and OCE_API_KEY in the process environment.
+2. Run `oce-client --root <workspace> sync --json`.
+3. Run `oce-client --root <workspace> retrieve --json "<natural-language question>"`.
+4. Parse JSON from stdout and use `formatted_retrieval` as code context.
+```
+
+Run `sync` again before a later retrieval when files may have changed. The
+client persists inventory and checkpoint state, so unchanged files are not
+uploaded again.
+
+### Session retrieval with a watcher
+
+For several questions against the same workspace:
+
+```text
+1. Run one successful `sync`.
+2. Start `oce-client --root <workspace> watch` and keep it running.
+3. Invoke `retrieve --json` for each AI question while the watcher is alive.
+4. Stop the watcher when the workspace session ends.
+```
+
+The watcher handles changed paths incrementally. If it is stopped, return to
+the one-shot workflow and run `sync` before retrieving.
+
+### Unsaved editor state
+
+When the agent has content that is not yet written to disk:
+
+```text
+oce-client --root <workspace> observe src/example.py --content "<text>"
+oce-client --root <workspace> sync --json
+oce-client --root <workspace> retrieve --json "<question>"
+```
+
+Use `remove` followed by `sync` for an unsaved deletion.
+
+## 3. Important Notes
+
+- This CLI handles one workspace per invocation. Pass the workspace explicitly
+  when the agent knows it; do not accidentally index the agent's own process
+  directory.
+- Keep `OCE_API_KEY` in the environment or a secret manager. Never put the key
+  in prompts, command arguments, logs, JSON output, or committed files.
+- Use `--json` whenever another program or agent will consume the result.
+  Treat stdout as the data channel and stderr as diagnostics.
+- A successful `status` only proves that local state exists; it does not prove
+  that the files on disk have been synchronized. Do not claim that retrieval is
+  current until `sync` has succeeded or an active `watch` has processed the
+  changes.
+- `sync` and `retrieve` can take time on a first run or after a large change.
+  Do not retry them concurrently against the same state file.
+- Use only the commands and options documented above. In particular, do not
+  invent a background or initial-sync option for this one-shot CLI.
+- Retrieval describes the current code on disk and the selected checkpoint. It
+  has no version-control history or knowledge of previous commits.
+- Quote workspace paths and natural-language queries. Use workspace-relative
+  paths with `observe` and `remove`.
+- A zero exit code means the command completed successfully. A non-zero exit
+  code means the result should not be treated as valid context; inspect stderr.

oce_client/skill/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Oce Client"
+  short_description: "Sync and retrieve workspace code"
+  default_prompt: "Use $oce-client to retrieve the relevant code context for this task."