yvgude--lean-ctx/clients/python/README.md

lean-ctx-client (Python SDK)

Thin, dependency-free Python client for the lean-ctx HTTP /v1 contract. Standard library only (urllib) — installs and runs anywhere, no transitive dependencies. It speaks the wire protocol only; it never links the engine or re-implements compression. Mirrors the TypeScript and Rust lean-ctx-client SDKs.

Install

pip install lean-ctx-client
# from this repo:
pip install ./clients/python

Usage

from leanctx import LeanCtxClient, run_conformance

client = LeanCtxClient("http://127.0.0.1:8080")

# Discovery
caps = client.capabilities()   # GET /v1/capabilities
api = client.openapi()         # GET /v1/openapi.json

# Tools
listing = client.list_tools(limit=10)
text = client.call_tool_text("ctx_read", {"path": "README.md"})

# Live events (SSE)
for event in client.subscribe_events():
    print(event["kind"], event["payload"])

Methods

Method	Endpoint
health()	GET /health
manifest()	GET /v1/manifest
capabilities()	GET /v1/capabilities
openapi()	GET /v1/openapi.json
list_tools(offset=, limit=)	GET /v1/tools
call_tool(name, arguments, ...)	POST /v1/tools/call
call_tool_text(name, arguments, ...)	POST /v1/tools/call + text extraction
subscribe_events(...)	GET /v1/events (SSE)
context_summary(...)	GET /v1/context/summary
search_events(q, ...)	GET /v1/events/search
event_lineage(event_id, ...)	GET /v1/events/lineage
metrics()	GET /v1/metrics

Shared conformance kit

run_conformance(client) runs the language-agnostic SDK conformance checks against a live server and returns a scorecard. It mirrors the TypeScript SDK's runConformance and the server-side lean-ctx conformance, keeping all clients in lockstep on the same contract.

card = run_conformance(client)
assert card.all_passed, [c for c in card.checks if not c.passed]

The kit covers every /v1 route (COVERED_ROUTES): its route_coverage check fails when the server advertises a route this SDK does not cover, and engine_compat fails when the server speaks an http_mcp contract version outside SUPPORTED_HTTP_CONTRACT_VERSIONS. The published matrix lives at docs/reference/sdk-conformance-matrix.md (regenerated by scripts/sdk-conformance.sh against a real server in the sdk-conformance CI job).

SemVer coupling

The SDK's major version follows the engine's http_mcp contract major (CONTRACTS.md § Versioning rules): a v2 contract ships as SDK 2.x, and 1.x keeps speaking v1.

Framework adapters

Expose the lean-ctx tool surface to popular agent frameworks. Each framework is an optional dependency, imported lazily — installing lean-ctx-client pulls in none of them. The OpenAI adapter is a pure transformation and needs no extra package.

from leanctx import LeanCtxClient
from leanctx.adapters import (
    to_openai_tools, run_openai_tool_call,   # no extra dep
    to_langchain_tools,                       # pip install "lean-ctx-client[langchain]"
    to_llamaindex_tools,                      # pip install "lean-ctx-client[llamaindex]"
    to_crewai_tools,                          # pip install "lean-ctx-client[crewai]"
)

client = LeanCtxClient("http://127.0.0.1:8080")

# OpenAI function calling
tools = to_openai_tools(client)
# ... pass tools to client.chat.completions.create(...), then:
text = run_openai_tool_call(client, tool_call)

# LangChain / LlamaIndex / CrewAI
lc_tools = to_langchain_tools(client)

Errors

• LeanCtxConfigError — invalid arguments / configuration (no I/O performed).
• LeanCtxTransportError — request never produced a response (network/DNS/TLS).
• LeanCtxHTTPError — non-2xx response, with status, method, url, error_code, and parsed body.

Non-goals

• No engine linkage and no re-implemented compression/indexing logic.
• Stability over surface: only the documented /v1 contract is exposed.

Development

cd clients/python
python -m pytest