koshi 0.4.0__tar.gz

koshi-0.4.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+dist/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

koshi-0.4.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: koshi
+Version: 0.4.0
+Summary: Python client for the Koshi MCP server — retrieval, memory, context, and quality tools for any LLM workflow. Auto-downloads a native AOT binary; no .NET install required.
+Project-URL: Homepage, https://github.com/jsharma1105/Koshi
+Project-URL: Documentation, https://github.com/jsharma1105/Koshi#readme
+Project-URL: Repository, https://github.com/jsharma1105/Koshi
+Project-URL: Issues, https://github.com/jsharma1105/Koshi/issues
+Project-URL: Changelog, https://github.com/jsharma1105/Koshi/blob/main/CHANGELOG.md
+Author: Koshi Contributors
+License: MIT
+Keywords: agent,ai,bm25,claude,context-engineering,copilot,cursor,llm,mcp,memory,model-context-protocol,rag,retrieval
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# koshi
+
+[![PyPI version](https://img.shields.io/pypi/v/koshi.svg)](https://pypi.org/project/koshi/)
+[![Python versions](https://img.shields.io/pypi/pyversions/koshi.svg)](https://pypi.org/project/koshi/)
+[![License](https://img.shields.io/pypi/l/koshi.svg)](https://github.com/jsharma1105/Koshi/blob/main/LICENSE)
+
+**Python client for the [Koshi MCP server](https://github.com/jsharma1105/Koshi).** Retrieval, memory, context engineering, and quality scoring for any LLM workflow — 20 tools, all wrapped as Pythonic methods.
+
+> No `.NET install` required. The first call auto-downloads a small native AOT binary (~15 MB) into your user cache.
+
+---
+
+## Install
+
+```bash
+pip install koshi
+```
+
+Requires Python 3.10+ on Linux x64/arm64, macOS x64/arm64, or Windows x64/arm64. Zero runtime dependencies — every byte is Python stdlib.
+
+## Quick start
+
+```python
+from koshi import Client
+
+with Client() as koshi:
+    print(koshi.version())                          # diagnostics
+    koshi.index_directory("/path/to/your/repo")     # BM25 index of all text files
+    print(koshi.search("auth pattern", top_k=5))    # ranked retrieval
+    koshi.remember(content="JWT tokens expire after 1h",
+                   subject="auth", type="Decision")
+    print(koshi.recall("auth"))                     # memory recall with recency + confidence
+```
+
+The first `Client()` call:
+
+1. Detects your OS/CPU.
+2. Looks for the matching `koshi-mcp` binary in `KOSHI_BIN` → versioned cache → `PATH` → GitHub release.
+3. Downloads, verifies SHA-256 (hashes are baked into the wheel — supply-chain safe), caches under your user cache dir.
+4. Spawns it as a subprocess, performs the MCP `initialize` handshake.
+5. Confirms the server's reported version matches the Python package version exactly. Mismatch raises `IncompatibleBinaryError`.
+
+## The 20 tools
+
+| Group | Methods |
+|---|---|
+| **Retrieval** | `index_directory`, `index`, `search`, `list_indexed`, `clear_index` |
+| **Memory** | `remember`, `recall`, `forget`, `memory_stats`, `clear_memories` |
+| **Context** | `compile_context`, `token_count`, `budget_plan` |
+| **Team / Quality** | `register_team`, `score_turn`, `team_dashboard`, `analyze_feedback`, `list_teams` |
+| **Diagnostics** | `version`, `health` |
+
+Every method returns the formatted text response from the MCP server. The full Koshi tool reference lives in the [main README](https://github.com/jsharma1105/Koshi#mcp-tools).
+
+## Environment variables
+
+| Var | Effect |
+|---|---|
+| `KOSHI_BIN` | Path to a `koshi-mcp` binary. Skips auto-download, overrides PATH lookup. Version still verified at spawn time. |
+| `KOSHI_MEMORY_FILE` | Persist memories to this JSON file across server restarts. Default: in-memory only. |
+| `KOSHI_INDEX_PATH` | Default directory for `search` / `index_directory` if you don't pass one. |
+
+## Where binaries live
+
+| OS | Cache path |
+|---|---|
+| Linux | `$XDG_CACHE_HOME/koshi/bin/<version>/` or `~/.cache/koshi/bin/<version>/` |
+| macOS | `~/Library/Caches/koshi/bin/<version>/` |
+| Windows | `%LOCALAPPDATA%\koshi\bin\<version>\` |
+
+The version is part of the path, so upgrading `pip install -U koshi` does not invalidate the cache for older Python projects pinned to an older `koshi` version.
+
+## Air-gapped / offline
+
+Download the binary that matches your platform from a GitHub release of [Koshi](https://github.com/jsharma1105/Koshi/releases) on a machine with internet, copy it onto the target machine, and point `KOSHI_BIN` at it. The version must match the installed `koshi` Python package exactly.
+
+## Error handling
+
+```python
+from koshi import (
+    Client,
+    KoshiError,            # base class
+    BinaryNotFoundError,   # nothing on disk + download failed
+    IncompatibleBinaryError,  # version mismatch
+    BinaryCorruptedError,  # SHA-256 mismatch
+    UnsupportedPlatformError,  # no AOT artifact for this OS/CPU
+    ProtocolError,         # malformed MCP message
+    ToolError,             # tool returned an error response
+    KoshiTimeoutError,     # request took longer than client.timeout
+)
+```
+
+## Why this exists
+
+Koshi's engine is .NET. That's a deliberate choice — the runtime gets us best-in-class JSON, threading, and a great MCP SDK. But it's also adoption friction: most MCP users live in Python.
+
+`koshi` (Python) closes the gap. You `pip install koshi` and never think about .NET. Under the hood, you're talking to the same engine the .NET ecosystem uses (`Koshi.Mcp` on NuGet), wire-compatible byte-for-byte.
+
+## Links
+
+- **Source & issues**: <https://github.com/jsharma1105/Koshi>
+- **Release binaries**: <https://github.com/jsharma1105/Koshi/releases>
+- **NuGet (.NET tool)**: <https://www.nuget.org/packages/Koshi.Mcp>
+- **Changelog**: <https://github.com/jsharma1105/Koshi/blob/main/CHANGELOG.md>
+
+## License
+
+MIT — see [LICENSE](https://github.com/jsharma1105/Koshi/blob/main/LICENSE).

koshi-0.4.0/README.md

@@ -0,0 +1,108 @@
+# koshi
+
+[![PyPI version](https://img.shields.io/pypi/v/koshi.svg)](https://pypi.org/project/koshi/)
+[![Python versions](https://img.shields.io/pypi/pyversions/koshi.svg)](https://pypi.org/project/koshi/)
+[![License](https://img.shields.io/pypi/l/koshi.svg)](https://github.com/jsharma1105/Koshi/blob/main/LICENSE)
+
+**Python client for the [Koshi MCP server](https://github.com/jsharma1105/Koshi).** Retrieval, memory, context engineering, and quality scoring for any LLM workflow — 20 tools, all wrapped as Pythonic methods.
+
+> No `.NET install` required. The first call auto-downloads a small native AOT binary (~15 MB) into your user cache.
+
+---
+
+## Install
+
+```bash
+pip install koshi
+```
+
+Requires Python 3.10+ on Linux x64/arm64, macOS x64/arm64, or Windows x64/arm64. Zero runtime dependencies — every byte is Python stdlib.
+
+## Quick start
+
+```python
+from koshi import Client
+
+with Client() as koshi:
+    print(koshi.version())                          # diagnostics
+    koshi.index_directory("/path/to/your/repo")     # BM25 index of all text files
+    print(koshi.search("auth pattern", top_k=5))    # ranked retrieval
+    koshi.remember(content="JWT tokens expire after 1h",
+                   subject="auth", type="Decision")
+    print(koshi.recall("auth"))                     # memory recall with recency + confidence
+```
+
+The first `Client()` call:
+
+1. Detects your OS/CPU.
+2. Looks for the matching `koshi-mcp` binary in `KOSHI_BIN` → versioned cache → `PATH` → GitHub release.
+3. Downloads, verifies SHA-256 (hashes are baked into the wheel — supply-chain safe), caches under your user cache dir.
+4. Spawns it as a subprocess, performs the MCP `initialize` handshake.
+5. Confirms the server's reported version matches the Python package version exactly. Mismatch raises `IncompatibleBinaryError`.
+
+## The 20 tools
+
+| Group | Methods |
+|---|---|
+| **Retrieval** | `index_directory`, `index`, `search`, `list_indexed`, `clear_index` |
+| **Memory** | `remember`, `recall`, `forget`, `memory_stats`, `clear_memories` |
+| **Context** | `compile_context`, `token_count`, `budget_plan` |
+| **Team / Quality** | `register_team`, `score_turn`, `team_dashboard`, `analyze_feedback`, `list_teams` |
+| **Diagnostics** | `version`, `health` |
+
+Every method returns the formatted text response from the MCP server. The full Koshi tool reference lives in the [main README](https://github.com/jsharma1105/Koshi#mcp-tools).
+
+## Environment variables
+
+| Var | Effect |
+|---|---|
+| `KOSHI_BIN` | Path to a `koshi-mcp` binary. Skips auto-download, overrides PATH lookup. Version still verified at spawn time. |
+| `KOSHI_MEMORY_FILE` | Persist memories to this JSON file across server restarts. Default: in-memory only. |
+| `KOSHI_INDEX_PATH` | Default directory for `search` / `index_directory` if you don't pass one. |
+
+## Where binaries live
+
+| OS | Cache path |
+|---|---|
+| Linux | `$XDG_CACHE_HOME/koshi/bin/<version>/` or `~/.cache/koshi/bin/<version>/` |
+| macOS | `~/Library/Caches/koshi/bin/<version>/` |
+| Windows | `%LOCALAPPDATA%\koshi\bin\<version>\` |
+
+The version is part of the path, so upgrading `pip install -U koshi` does not invalidate the cache for older Python projects pinned to an older `koshi` version.
+
+## Air-gapped / offline
+
+Download the binary that matches your platform from a GitHub release of [Koshi](https://github.com/jsharma1105/Koshi/releases) on a machine with internet, copy it onto the target machine, and point `KOSHI_BIN` at it. The version must match the installed `koshi` Python package exactly.
+
+## Error handling
+
+```python
+from koshi import (
+    Client,
+    KoshiError,            # base class
+    BinaryNotFoundError,   # nothing on disk + download failed
+    IncompatibleBinaryError,  # version mismatch
+    BinaryCorruptedError,  # SHA-256 mismatch
+    UnsupportedPlatformError,  # no AOT artifact for this OS/CPU
+    ProtocolError,         # malformed MCP message
+    ToolError,             # tool returned an error response
+    KoshiTimeoutError,     # request took longer than client.timeout
+)
+```
+
+## Why this exists
+
+Koshi's engine is .NET. That's a deliberate choice — the runtime gets us best-in-class JSON, threading, and a great MCP SDK. But it's also adoption friction: most MCP users live in Python.
+
+`koshi` (Python) closes the gap. You `pip install koshi` and never think about .NET. Under the hood, you're talking to the same engine the .NET ecosystem uses (`Koshi.Mcp` on NuGet), wire-compatible byte-for-byte.
+
+## Links
+
+- **Source & issues**: <https://github.com/jsharma1105/Koshi>
+- **Release binaries**: <https://github.com/jsharma1105/Koshi/releases>
+- **NuGet (.NET tool)**: <https://www.nuget.org/packages/Koshi.Mcp>
+- **Changelog**: <https://github.com/jsharma1105/Koshi/blob/main/CHANGELOG.md>
+
+## License
+
+MIT — see [LICENSE](https://github.com/jsharma1105/Koshi/blob/main/LICENSE).

koshi-0.4.0/pyproject.toml

@@ -0,0 +1,108 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "koshi"
+version = "0.4.0"
+description = "Python client for the Koshi MCP server — retrieval, memory, context, and quality tools for any LLM workflow. Auto-downloads a native AOT binary; no .NET install required."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [
+    { name = "Koshi Contributors" },
+]
+keywords = [
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "llm",
+    "rag",
+    "retrieval",
+    "bm25",
+    "context-engineering",
+    "memory",
+    "agent",
+    "claude",
+    "copilot",
+    "cursor",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS :: MacOS X",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+# Intentionally zero runtime dependencies — every byte is stdlib.
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-timeout>=2.3",
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "build>=1.2",
+    "twine>=5.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/jsharma1105/Koshi"
+Documentation = "https://github.com/jsharma1105/Koshi#readme"
+Repository = "https://github.com/jsharma1105/Koshi"
+Issues = "https://github.com/jsharma1105/Koshi/issues"
+Changelog = "https://github.com/jsharma1105/Koshi/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/koshi"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/koshi/**/*.py",
+    "src/koshi/py.typed",
+    "README.md",
+    "pyproject.toml",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF"]
+ignore = [
+    "E501",  # handled by formatter
+]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src/koshi"]
+warn_unused_configs = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+no_implicit_reexport = true
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+addopts = [
+    "-ra",
+    "--strict-markers",
+    "--strict-config",
+]
+markers = [
+    "slow: tests that spawn a real koshi-mcp subprocess (deselect with -m 'not slow')",
+]
+timeout = 60

koshi-0.4.0/src/koshi/__init__.py

@@ -0,0 +1,45 @@
+"""
+koshi — Python client for the Koshi MCP server.
+
+Quickstart::
+
+    from koshi import Client
+
+    with Client() as koshi:
+        print(koshi.version())
+        koshi.index_directory("/path/to/repo")
+        print(koshi.search("auth pattern", top_k=5))
+
+The first call auto-downloads the matching native AOT binary (~15 MB)
+into your user cache. No .NET install required. Set ``KOSHI_BIN`` to
+override the resolver with an explicit path (e.g. an air-gapped
+deployment, or a build of your own).
+"""
+
+from __future__ import annotations
+
+from ._manifest import VERSION as __version__
+from .client import Client
+from .errors import (
+    BinaryCorruptedError,
+    BinaryNotFoundError,
+    IncompatibleBinaryError,
+    KoshiError,
+    KoshiTimeoutError,
+    ProtocolError,
+    ToolError,
+    UnsupportedPlatformError,
+)
+
+__all__ = [
+    "BinaryCorruptedError",
+    "BinaryNotFoundError",
+    "Client",
+    "IncompatibleBinaryError",
+    "KoshiError",
+    "KoshiTimeoutError",
+    "ProtocolError",
+    "ToolError",
+    "UnsupportedPlatformError",
+    "__version__",
+]

koshi-0.4.0/src/koshi/_manifest.py

@@ -0,0 +1,38 @@
+"""
+AUTO-GENERATED at release time by scripts/inject-manifest.py.
+DO NOT EDIT BY HAND. Re-run from the release workflow if it needs to change.
+
+Binds this Python wheel to the exact AOT binaries published in the
+matching GitHub release. The binary auto-downloader verifies every
+fetched binary against EXPECTED_BINARIES; a tampered binary on the
+GitHub release alone is not enough to compromise users.
+"""
+
+from __future__ import annotations
+
+VERSION: str = "0.4.0"
+
+RELEASE_URL_TEMPLATE: str = "https://github.com/jsharma1105/Koshi/releases/download/v{version}/{filename}"
+
+EXPECTED_BINARIES: dict[str, dict[str, str]] = {
+    "linux-arm64": {
+        "filename": "koshi-mcp-linux-arm64",
+        "sha256":   "9534bb3bf856d84c7b62d05dc04a9749b43c92f24e5b474f12cd5e7276ffd347",
+    },
+    "linux-x64": {
+        "filename": "koshi-mcp-linux-x64",
+        "sha256":   "50580dd397bcca12b97a2385cc75babb32dc426015b03fbee1d3eb3ff4baac97",
+    },
+    "osx-arm64": {
+        "filename": "koshi-mcp-osx-arm64",
+        "sha256":   "2bc707ffee8f1a42208da68fcbe2814ce849dc7594b57915ef524d362e1c1768",
+    },
+    "win-arm64": {
+        "filename": "koshi-mcp-win-arm64.exe",
+        "sha256":   "0b1b8e8469803113ef0cc74e5a87219a51f8977097fea1fb4e9f38d7e4c3546c",
+    },
+    "win-x64": {
+        "filename": "koshi-mcp-win-x64.exe",
+        "sha256":   "9c9645c1d635aa5be27837d88644b83411169acf91c68bd292e49f5b624f061c",
+    },
+}

koshi-0.4.0/src/koshi/binary.py

@@ -0,0 +1,251 @@
+"""
+Resolve and (if needed) download the koshi-mcp AOT binary.
+
+Resolution order:
+  1. ``KOSHI_BIN`` env var (explicit override; version is verified after spawn).
+  2. Versioned cache: ``<cache>/koshi/bin/<VERSION>/koshi-mcp-<rid>[.exe]``.
+     The path itself is version-pinned, so a hit cannot be stale.
+  3. ``shutil.which("koshi-mcp")`` (e.g. installed via ``dotnet tool install``);
+     version is verified after spawn.
+  4. Download from the matching GitHub release with strict SHA-256
+     verification against the hashes embedded in ``_manifest.py``.
+
+Atomicity: downloads write to a temp file, are hash-verified, then renamed
+with ``os.replace`` (atomic on every supported OS).
+
+Concurrency: a per-version file lock protects the cache so two processes
+constructing ``Client()`` at the same time cannot both fetch the binary.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import os
+import platform
+import shutil
+import sys
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from ._manifest import EXPECTED_BINARIES, RELEASE_URL_TEMPLATE, VERSION
+from .errors import (
+    BinaryCorruptedError,
+    BinaryNotFoundError,
+    UnsupportedPlatformError,
+)
+
+_RID_MAP: dict[tuple[str, str], str] = {
+    ("Linux", "x86_64"): "linux-x64",
+    ("Linux", "aarch64"): "linux-arm64",
+    ("Linux", "arm64"): "linux-arm64",
+    # ("Darwin", "x86_64"): "osx-x64",  # Intel Mac not published as of v0.4.0
+    ("Darwin", "arm64"): "osx-arm64",
+    ("Windows", "AMD64"): "win-x64",
+    ("Windows", "x86_64"): "win-x64",
+    ("Windows", "ARM64"): "win-arm64",
+}
+
+_DOWNLOAD_TIMEOUT_S = 60
+_DOWNLOAD_CHUNK = 1 << 16  # 64 KiB
+
+
+def detect_rid() -> str:
+    """Return the .NET RID for the current OS/CPU, raising on unsupported combos."""
+    system = platform.system()
+    machine = platform.machine()
+    rid = _RID_MAP.get((system, machine))
+    if rid is None:
+        hint = ""
+        if system == "Darwin" and machine == "x86_64":
+            hint = (
+                " (Intel Macs are not in the AOT release matrix as of v0.4.0; "
+                "Apple stopped shipping Intel Macs in 2023.)"
+            )
+        raise UnsupportedPlatformError(
+            f"No published Koshi AOT artifact for {system}/{machine}.{hint} "
+            f"Install .NET 10 and `dotnet tool install --global Koshi.Mcp` instead, "
+            f"then set KOSHI_BIN to the resulting koshi-mcp executable."
+        )
+    return rid
+
+
+def _cache_root() -> Path:
+    """Return the OS-appropriate cache root (stdlib-only — no platformdirs)."""
+    if sys.platform == "win32":
+        base = os.environ.get("LOCALAPPDATA") or str(Path.home() / "AppData" / "Local")
+    elif sys.platform == "darwin":
+        base = str(Path.home() / "Library" / "Caches")
+    else:
+        base = os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache")
+    return Path(base) / "koshi"
+
+
+def versioned_cache_dir() -> Path:
+    return _cache_root() / "bin" / VERSION
+
+
+def _binary_filename(rid: str) -> str:
+    info = EXPECTED_BINARIES.get(rid)
+    if info is not None:
+        return info["filename"]
+    return f"koshi-mcp-{rid}{'.exe' if rid.startswith('win-') else ''}"
+
+
+def _sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        for chunk in iter(lambda: f.read(_DOWNLOAD_CHUNK), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+@contextmanager
+def _file_lock(lock_path: Path) -> Iterator[None]:
+    """Best-effort cross-platform exclusive lock on ``lock_path``."""
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(str(lock_path), os.O_CREAT | os.O_RDWR, 0o600)
+    try:
+        if sys.platform == "win32":
+            import msvcrt
+
+            for _ in range(600):  # ≤ 60 s
+                try:
+                    msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+                    break
+                except OSError:
+                    time.sleep(0.1)
+            else:
+                raise BinaryNotFoundError(
+                    f"Timed out acquiring cache lock {lock_path}"
+                )
+        else:
+            import fcntl
+
+            fcntl.flock(fd, fcntl.LOCK_EX)
+        yield
+    finally:
+        try:
+            if sys.platform == "win32":
+                import msvcrt
+
+                with contextlib.suppress(OSError):
+                    msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+            else:
+                import fcntl
+
+                fcntl.flock(fd, fcntl.LOCK_UN)
+        finally:
+            os.close(fd)
+
+
+def _atomic_download(url: str, dest: Path, expected_sha256: str | None) -> None:
+    """Download ``url`` to ``dest`` atomically. Raise on hash mismatch."""
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    tmp = dest.parent / f".{dest.name}.{os.getpid()}.{int(time.time_ns())}.tmp"
+
+    headers = {"User-Agent": f"koshi-py/{VERSION}", "Accept": "application/octet-stream"}
+    request = Request(url, headers=headers)
+    try:
+        with urlopen(request, timeout=_DOWNLOAD_TIMEOUT_S) as resp:
+            if resp.status != 200:
+                raise BinaryNotFoundError(
+                    f"Failed to download {url}: HTTP {resp.status}"
+                )
+            with tmp.open("wb") as f:
+                while True:
+                    chunk = resp.read(_DOWNLOAD_CHUNK)
+                    if not chunk:
+                        break
+                    f.write(chunk)
+    except HTTPError as e:
+        tmp.unlink(missing_ok=True)
+        raise BinaryNotFoundError(f"HTTP {e.code} fetching {url}: {e.reason}") from e
+    except URLError as e:
+        tmp.unlink(missing_ok=True)
+        raise BinaryNotFoundError(f"Network error fetching {url}: {e.reason}") from e
+
+    try:
+        if expected_sha256 is not None:
+            actual = _sha256_file(tmp)
+            if actual.lower() != expected_sha256.lower():
+                raise BinaryCorruptedError(
+                    f"Downloaded binary hash mismatch for {dest.name}: "
+                    f"expected {expected_sha256}, got {actual}"
+                )
+
+        if os.name != "nt":
+            os.chmod(tmp, 0o755)
+
+        os.replace(tmp, dest)
+    finally:
+        # If replace() above succeeded, tmp no longer exists; this is a safety net.
+        with contextlib.suppress(FileNotFoundError):
+            tmp.unlink()
+
+
+def _download_to_cache(rid: str) -> Path:
+    """Download the matching AOT binary into the versioned cache."""
+    expected = EXPECTED_BINARIES.get(rid)
+    if expected is None:
+        raise BinaryNotFoundError(
+            f"This dev build of koshi has no manifest entry for {rid}. "
+            f"Either install koshi-mcp via `dotnet tool install --global Koshi.Mcp`, "
+            f"or set KOSHI_BIN to a built koshi-mcp binary, or install koshi from PyPI."
+        )
+
+    filename = expected["filename"]
+    sha256 = expected["sha256"]
+    url = RELEASE_URL_TEMPLATE.format(version=VERSION, filename=filename)
+
+    cache_dir = versioned_cache_dir()
+    dest = cache_dir / filename
+    lock = cache_dir / ".lock"
+
+    with _file_lock(lock):
+        # Another process may have completed the download while we waited.
+        if dest.exists() and _sha256_file(dest) == sha256:
+            return dest
+        _atomic_download(url, dest, expected_sha256=sha256)
+    return dest
+
+
+def resolve_binary() -> Path:
+    """
+    Resolve the koshi-mcp binary by walking the resolution chain.
+
+    Version-matching is enforced at spawn time by :class:`koshi.Client` via
+    the ``serverInfo.version`` returned during MCP initialize, not here.
+    This function's job is only to return *some* path that exists.
+    """
+    rid = detect_rid()
+
+    env_bin = os.environ.get("KOSHI_BIN")
+    if env_bin:
+        p = Path(env_bin)
+        if not p.exists():
+            raise BinaryNotFoundError(
+                f"KOSHI_BIN is set to '{env_bin}' but that path does not exist."
+            )
+        return p
+
+    cached = versioned_cache_dir() / _binary_filename(rid)
+    if cached.exists():
+        info = EXPECTED_BINARIES.get(rid)
+        if info is not None:
+            if _sha256_file(cached) == info["sha256"]:
+                return cached
+            with contextlib.suppress(OSError):
+                cached.unlink()
+        else:
+            return cached
+
+    on_path = shutil.which("koshi-mcp") or shutil.which("koshi-mcp.exe")
+    if on_path:
+        return Path(on_path)
+
+    return _download_to_cache(rid)

koshi-0.4.0/src/koshi/client.py

@@ -0,0 +1,471 @@
+"""
+Synchronous MCP client for the koshi-mcp server.
+
+Spawns the koshi-mcp binary as a subprocess, performs the JSON-RPC 2.0
+``initialize`` / ``notifications/initialized`` handshake, then exposes
+one Python method per Koshi MCP tool. Every tool method is a thin
+wrapper around the MCP ``tools/call`` envelope — the wire format is
+fixed and asserted in the test suite.
+
+Threading: each ``Client`` is safe for use from a single thread (or
+under a user-supplied lock). The internal lock serialises request /
+response correlation; it is not a re-entrant lock.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import subprocess
+import sys
+import threading
+import time
+from collections.abc import Callable, Mapping
+from pathlib import Path
+from types import TracebackType
+from typing import Any
+
+from ._manifest import VERSION
+from .binary import resolve_binary
+from .errors import (
+    IncompatibleBinaryError,
+    KoshiError,
+    KoshiTimeoutError,
+    ProtocolError,
+    ToolError,
+)
+
+__all__ = ["Client"]
+
+_LogHandler = Callable[[str], None]
+
+
+class Client:
+    """Stdio MCP client bound to a single koshi-mcp subprocess.
+
+    Use as a context manager::
+
+        with koshi.Client() as c:
+            print(c.version())
+            c.index_directory("/path/to/repo")
+            print(c.search("auth pattern"))
+
+    Or manage lifecycle manually::
+
+        c = koshi.Client()
+        c.open()
+        try:
+            print(c.health())
+        finally:
+            c.close()
+    """
+
+    def __init__(
+        self,
+        binary: str | Path | None = None,
+        log_handler: _LogHandler | None = None,
+        timeout: float = 15.0,
+    ) -> None:
+        self._binary_arg: Path | None = Path(binary) if binary is not None else None
+        self._log_handler = log_handler
+        self.timeout = timeout
+
+        self._binary: Path | None = None
+        self._proc: subprocess.Popen[str] | None = None
+        self._next_id = 0
+        self._lock = threading.Lock()
+        self._stderr_thread: threading.Thread | None = None
+        self._server_version: str | None = None
+
+    # ─── lifecycle ───────────────────────────────────────────────────────
+
+    def __enter__(self) -> Client:
+        self.open()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def open(self) -> None:
+        if self._proc is not None:
+            return
+
+        self._binary = self._binary_arg or resolve_binary()
+
+        # text=True + line buffering means every JSON document is a single
+        # readline()/write() call. Koshi-mcp emits one document per line.
+        self._proc = subprocess.Popen(
+            [str(self._binary)],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            bufsize=1,
+            encoding="utf-8",
+        )
+
+        self._stderr_thread = threading.Thread(target=self._drain_stderr, daemon=True)
+        self._stderr_thread.start()
+
+        try:
+            init = self._rpc(
+                "initialize",
+                {
+                    "protocolVersion": "2024-11-05",
+                    "capabilities": {},
+                    "clientInfo": {"name": "koshi-py", "version": VERSION},
+                },
+            )
+        except KoshiError:
+            self.close()
+            raise
+
+        server_info = init.get("serverInfo") or {}
+        raw_version = str(server_info.get("version", ""))
+        # Strip "+<git-sha>" if present (InformationalVersionAttribute appends it).
+        version_core = raw_version.split("+", 1)[0]
+        self._server_version = version_core
+
+        if version_core and version_core != VERSION:
+            self.close()
+            raise IncompatibleBinaryError(
+                f"Resolved koshi-mcp binary reports version '{raw_version}', "
+                f"but Python koshi {VERSION} requires an exact-version match. "
+                f"Either upgrade koshi-mcp to {VERSION}, downgrade `pip install koshi=={version_core}`, "
+                f"unset KOSHI_BIN, or remove the stale `dotnet tool install` of Koshi.Mcp from PATH."
+            )
+
+        self._notify("notifications/initialized")
+
+    def close(self) -> None:
+        proc = self._proc
+        if proc is None:
+            return
+        self._proc = None
+        try:
+            if proc.stdin is not None:
+                with contextlib.suppress(OSError):
+                    proc.stdin.close()
+            try:
+                proc.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+                with contextlib.suppress(subprocess.TimeoutExpired):
+                    proc.wait(timeout=2)
+        finally:
+            self._server_version = None
+
+    # ─── transport ──────────────────────────────────────────────────────
+
+    def _drain_stderr(self) -> None:
+        proc = self._proc
+        if proc is None or proc.stderr is None:
+            return
+        try:
+            for line in proc.stderr:
+                line = line.rstrip("\n")
+                if self._log_handler is not None:
+                    # Never let a user log handler crash the drainer.
+                    with contextlib.suppress(Exception):
+                        self._log_handler(line)
+        except (ValueError, OSError):
+            return
+
+    def _ensure_open(self) -> subprocess.Popen[str]:
+        if self._proc is None:
+            raise ProtocolError("Client is not open. Call .open() or use `with` statement.")
+        return self._proc
+
+    def _send_line(self, payload: Mapping[str, Any]) -> None:
+        proc = self._ensure_open()
+        if proc.stdin is None:
+            raise ProtocolError("subprocess stdin is unexpectedly None")
+        proc.stdin.write(json.dumps(payload, separators=(",", ":")) + "\n")
+        proc.stdin.flush()
+
+    def _rpc(self, method: str, params: Mapping[str, Any] | None = None) -> dict[str, Any]:
+        with self._lock:
+            self._next_id += 1
+            req_id = self._next_id
+            payload: dict[str, Any] = {"jsonrpc": "2.0", "id": req_id, "method": method}
+            if params is not None:
+                payload["params"] = params
+
+            self._send_line(payload)
+
+            proc = self._ensure_open()
+            assert proc.stdout is not None
+
+            deadline = time.monotonic() + self.timeout
+            while True:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise KoshiTimeoutError(
+                        f"No response to '{method}' within {self.timeout:.1f}s"
+                    )
+
+                line = proc.stdout.readline()
+                if not line:
+                    raise ProtocolError(
+                        f"koshi-mcp closed stdout while waiting for '{method}' response"
+                    )
+
+                line = line.strip()
+                if not line:
+                    continue
+
+                try:
+                    msg = json.loads(line)
+                except json.JSONDecodeError as e:
+                    raise ProtocolError(
+                        f"Non-JSON line on stdout while waiting for '{method}': {line!r}"
+                    ) from e
+
+                if msg.get("id") != req_id:
+                    # Stray notification or out-of-order reply; ignore and keep reading.
+                    continue
+
+                if "error" in msg:
+                    err = msg["error"]
+                    raise ProtocolError(
+                        f"{method}: {err.get('message', err)} (code {err.get('code')})"
+                    )
+
+                return msg.get("result") or {}
+
+    def _notify(self, method: str, params: Mapping[str, Any] | None = None) -> None:
+        with self._lock:
+            payload: dict[str, Any] = {"jsonrpc": "2.0", "method": method}
+            if params is not None:
+                payload["params"] = params
+            self._send_line(payload)
+
+    def _tool_call(self, tool: str, arguments: Mapping[str, Any] | None = None) -> str:
+        result = self._rpc("tools/call", {"name": tool, "arguments": dict(arguments or {})})
+        content = result.get("content") or []
+        text = ""
+        if content and isinstance(content, list):
+            first = content[0]
+            if isinstance(first, dict):
+                text = str(first.get("text", ""))
+
+        is_error = bool(result.get("isError"))
+        if is_error or text.startswith("❌"):
+            raise ToolError(tool, text or "tool returned an error", raw=result)
+        return text
+
+    # ─── server metadata ────────────────────────────────────────────────
+
+    @property
+    def server_version(self) -> str | None:
+        """Version reported by the koshi-mcp server during initialize (or None)."""
+        return self._server_version
+
+    @property
+    def binary_path(self) -> Path | None:
+        """Filesystem path of the koshi-mcp binary actually spawned."""
+        return self._binary
+
+    # ─── Retrieval (5) ──────────────────────────────────────────────────
+
+    def index(self, documents: list[Mapping[str, Any]]) -> str:
+        """Index a list of in-memory documents for BM25 retrieval."""
+        return self._tool_call("koshi_index", {"documents": json.dumps(documents)})
+
+    def index_directory(
+        self,
+        path: str | None = None,
+        pattern: str | None = None,
+        max_file_size_kb: int = 256,
+        max_files: int = 5000,
+    ) -> str:
+        """Recursively index supported text files under ``path``."""
+        args: dict[str, Any] = {"maxFileSizeKb": max_file_size_kb, "maxFiles": max_files}
+        if path is not None:
+            args["path"] = path
+        if pattern is not None:
+            args["pattern"] = pattern
+        return self._tool_call("koshi_index_directory", args)
+
+    def search(self, query: str, top_k: int = 5) -> str:
+        """Search the indexed corpus with BM25; return the top ``top_k`` chunks."""
+        return self._tool_call("koshi_search", {"query": query, "topK": top_k})
+
+    def list_indexed(self) -> str:
+        """List all indexed documents grouped by source."""
+        return self._tool_call("koshi_list_indexed")
+
+    def clear_index(self) -> str:
+        """Clear the indexed corpus."""
+        return self._tool_call("koshi_clear_index")
+
+    # ─── Memory (5) ─────────────────────────────────────────────────────
+
+    def remember(
+        self,
+        content: str,
+        subject: str,
+        type: str = "Fact",
+        confidence: float = 0.8,
+        source: str = "user",
+    ) -> str:
+        """Store a fact / decision / pattern / preference in memory."""
+        return self._tool_call(
+            "koshi_remember",
+            {
+                "content": content,
+                "subject": subject,
+                "type": type,
+                "confidence": confidence,
+                "source": source,
+            },
+        )
+
+    def recall(self, query: str, type: str = "All", top_k: int = 5) -> str:
+        """Recall memories relevant to ``query``."""
+        return self._tool_call(
+            "koshi_recall",
+            {"query": query, "type": type, "topK": top_k},
+        )
+
+    def memory_stats(self) -> str:
+        """Return summary stats about the memory store."""
+        return self._tool_call("koshi_memory_stats")
+
+    def forget(self, subject: str) -> str:
+        """Remove all memories with the given subject (case-insensitive)."""
+        return self._tool_call("koshi_forget", {"subject": subject})
+
+    def clear_memories(self, confirm: bool = False) -> str:
+        """Clear ALL stored memories. Pass ``confirm=True`` to actually delete."""
+        return self._tool_call("koshi_clear_memories", {"confirm": confirm})
+
+    # ─── Context (3) ────────────────────────────────────────────────────
+
+    def compile_context(
+        self,
+        system_prompt: str,
+        user_query: str,
+        retrieved_content: str | None = None,
+        memories: str | None = None,
+        team_context: str | None = None,
+        token_budget: int = 8192,
+        strategy: str = "CacheOptimized",
+    ) -> str:
+        """Compile a context bundle suitable for an LLM call."""
+        args: dict[str, Any] = {
+            "systemPrompt": system_prompt,
+            "userQuery": user_query,
+            "tokenBudget": token_budget,
+            "strategy": strategy,
+        }
+        if retrieved_content is not None:
+            args["retrievedContent"] = retrieved_content
+        if memories is not None:
+            args["memories"] = memories
+        if team_context is not None:
+            args["teamContext"] = team_context
+        return self._tool_call("koshi_compile_context", args)
+
+    def token_count(self, text: str) -> str:
+        """Count GPT-4 (cl100k) tokens in ``text``."""
+        return self._tool_call("koshi_token_count", {"text": text})
+
+    def budget_plan(
+        self,
+        total_budget: int = 8192,
+        system_prompt: str | None = None,
+        team_context: str | None = None,
+    ) -> str:
+        """Plan a token budget across system / retrieval / memory / history."""
+        args: dict[str, Any] = {"totalBudget": total_budget}
+        if system_prompt is not None:
+            args["systemPrompt"] = system_prompt
+        if team_context is not None:
+            args["teamContext"] = team_context
+        return self._tool_call("koshi_budget_plan", args)
+
+    # ─── Team / Quality (5) ─────────────────────────────────────────────
+
+    def register_team(
+        self,
+        team_id: str,
+        name: str,
+        description: str | None = None,
+        token_budget: int = 8192,
+        top_k: int = 5,
+        quality_target: float = 0.7,
+        system_prompt: str | None = None,
+        team_context: str | None = None,
+    ) -> str:
+        """Register a team for quality scoring."""
+        args: dict[str, Any] = {
+            "teamId": team_id,
+            "name": name,
+            "tokenBudget": token_budget,
+            "topK": top_k,
+            "qualityTarget": quality_target,
+        }
+        if description is not None:
+            args["description"] = description
+        if system_prompt is not None:
+            args["systemPrompt"] = system_prompt
+        if team_context is not None:
+            args["teamContext"] = team_context
+        return self._tool_call("koshi_register_team", args)
+
+    def score_turn(
+        self,
+        team_id: str,
+        retrieved_chunks: int = 0,
+        memories_recalled: int = 0,
+        budget_utilization: float = 0.5,
+        cache_ratio: float = 0.0,
+        latency_ms: int = 3000,
+        user_rating: int = 0,
+        issues: str | None = None,
+    ) -> str:
+        """Score a single turn and update the team's running quality score."""
+        args: dict[str, Any] = {
+            "teamId": team_id,
+            "retrievedChunks": retrieved_chunks,
+            "memoriesRecalled": memories_recalled,
+            "budgetUtilization": budget_utilization,
+            "cacheRatio": cache_ratio,
+            "latencyMs": latency_ms,
+            "userRating": user_rating,
+        }
+        if issues is not None:
+            args["issues"] = issues
+        return self._tool_call("koshi_score_turn", args)
+
+    def team_dashboard(self, team_id: str) -> str:
+        """Render the quality dashboard for a team."""
+        return self._tool_call("koshi_team_dashboard", {"teamId": team_id})
+
+    def analyze_feedback(self, team_id: str) -> str:
+        """Analyse user feedback trends for a team."""
+        return self._tool_call("koshi_analyze_feedback", {"teamId": team_id})
+
+    def list_teams(self) -> str:
+        """List all registered teams."""
+        return self._tool_call("koshi_list_teams")
+
+    # ─── Diagnostics (2) ────────────────────────────────────────────────
+
+    def version(self) -> str:
+        """Report Koshi MCP server version, .NET runtime, OS, and uptime."""
+        return self._tool_call("koshi_version")
+
+    def health(self) -> str:
+        """Report runtime health: indexed corpus, memory, persistence, uptime."""
+        return self._tool_call("koshi_health")
+
+
+if sys.version_info < (3, 10):  # pragma: no cover  # noqa: UP036
+    raise RuntimeError("koshi requires Python 3.10 or newer.")

koshi-0.4.0/src/koshi/errors.py

@@ -0,0 +1,50 @@
+"""Exception hierarchy for the koshi Python client."""
+
+from __future__ import annotations
+
+
+class KoshiError(Exception):
+    """Base class for all koshi errors."""
+
+
+class BinaryNotFoundError(KoshiError):
+    """No suitable koshi-mcp binary was found on this system."""
+
+
+class IncompatibleBinaryError(KoshiError):
+    """The resolved binary's version does not match this koshi package.
+
+    Raised when:
+      * KOSHI_BIN points to a binary whose `serverInfo.version` differs from
+        koshi.__version__.
+      * A binary found on PATH (e.g. an old `dotnet tool install` of
+        Koshi.Mcp) has a mismatched version.
+
+    The Python package and the koshi-mcp binary version must match exactly.
+    """
+
+
+class BinaryCorruptedError(KoshiError):
+    """A downloaded binary's SHA-256 hash did not match the expected hash."""
+
+
+class UnsupportedPlatformError(KoshiError):
+    """No AOT artifact is published for this OS/CPU combination."""
+
+
+class ProtocolError(KoshiError):
+    """Received an unexpected or malformed message from the koshi-mcp server."""
+
+
+class ToolError(KoshiError):
+    """The MCP server returned an error response for a tools/call request."""
+
+    def __init__(self, tool: str, message: str, raw: object | None = None) -> None:
+        self.tool = tool
+        self.message = message
+        self.raw = raw
+        super().__init__(f"{tool}: {message}")
+
+
+class KoshiTimeoutError(KoshiError):
+    """A request to the koshi-mcp server timed out before a response arrived."""