LLMSlim v0.5.0

LLMSlim is a Python library for extractive, rewrite, and hybrid LLM-context compression. Its default compression path remains local and deterministic.

Tool-aware context, without rewriting the contract

v0.5.0 adds optional MCP catalog ingestion and a host-owned OpenAI Agents SDK bridge. Full tool exposure is the default; selective exposure remains research-only.

v0.4.0 introduced a contract-safe tool-schema layer for agent and MCP workflows. It can normalize supported provider shapes, deterministically canonicalize copied JSON, fingerprint complete definitions with SHA-256, check exact contract equivalence, and measure safe catalog representation changes. Authoritative raw schemas are never rewritten for execution.

Tool retrieval is included for research only. TF-IDF, BM25, optional semantic retrieval, hybrid RRF, selective exposure, and lazy hydration are not enabled by compress() and must not be used as authorization or execution decisions.

Install

pip install llmslim

# Optional local semantic retrieval support
pip install "llmslim[semantic]"

# Optional production MCP catalog integration (Python 3.10+)
pip install "llmslim[mcp]"

# Optional OpenAI Agents SDK bridge (Python 3.10+)
pip install "llmslim[agents]"

Python 3.8+ is supported. The semantic extra is optional; the normal package does not require sentence-transformers, PyTorch, or model downloads.

Compression quick start

from llmslim import ContextRole, compress

result = compress(
    "Long context goes here...",
    target_ratio=0.5,
    strategy="extractive",
    context_role=ContextRole.GENERAL,
)

print(result.compressed_text)
print(result.original_tokens, result.compressed_tokens)

extractive is the default local strategy. rewrite and hybrid require a caller-supplied provider. See SECURITY.md for the provenance boundary applied to ContextRole values.

Stable tool-contract APIs

Import stable tool-contract APIs from llmslim.tools:

from llmslim.tools import (
    canonical_json,
    contract_equivalent,
    fingerprint_tool_schema,
    from_mcp_tool,
    optimize_tool_schema,
)

raw = {
    "name": "calendar.search_events",
    "description": "Find calendar events.",
    "inputSchema": {
        "type": "object",
        "properties": {"query": {"type": "string"}},
        "required": ["query"],
    },
}

tool = from_mcp_tool(raw, namespace="calendar")
result = optimize_tool_schema(tool)

assert result.equivalence.status.value == "EXACT"
assert fingerprint_tool_schema(tool) == fingerprint_tool_schema(result.optimized)
print(canonical_json(result.optimized.raw))

Supported adapters cover MCP, OpenAI function, Anthropic tools, and a generic shape. They preserve copied raw definitions; cross-provider output is an adapter view, not proof that another provider will accept or authorize it. Read the tool API guide before integrating.

Unreleased MCP catalog integration

Phase 5 adds an optional, async integration layer for ingesting configured MCP tools/list catalogs through the official SDK. It preserves full authoritative schemas, honors bounded cache/pagination behavior, measures model context, and can produce a full-catalog plan by default. Hosts retain authorization and execution authority; LLMSlim never automatically calls a selected tool.

from llmslim.mcp import MCPToolCatalogSource, PlanMode, plan_catalog_context

source = MCPToolCatalogSource.from_streamable_http(
    "https://trusted.example.com/mcp",  # caller-owned configuration
    headers={"Authorization": "Bearer <configured-secret>"},
)
snapshot = await source.list_tools()
plan = plan_catalog_context(snapshot, mode=PlanMode.MEASURE_ONLY)
print(plan.metrics.catalog_tokens)

HTTP is restricted to localhost development. For local stdio, provide an explicit executable and argv—not a shell command. The optional SELECTIVE mode remains research-only and requires an explicit experimental=True opt-in. See Phase 5 documentation.

Experimental tool retrieval — research only

from llmslim.tool_retrieval import BM25ToolRetriever
from llmslim.tools import from_mcp_tool

catalog = [from_mcp_tool(raw, namespace="calendar")]
hits = BM25ToolRetriever(catalog).rank("find my events", limit=1)
print(hits[0].tool.tool_id)

The optional dense backend uses intfloat/multilingual-e5-small at pinned revision 0e60b8d9d2166d80387f86e3b48ec9ced55f4d15. It is local-cache-only: the package never downloads it automatically. Details and limitations are in the experimental retrieval guide.

Benchmarks and limitations

The v0.4.0 schema-tax measurement covers 375 schemas across 18 catalogs. Its lossless reduction was 0 tokens (0.00%), because the baseline was already compact canonical JSON. That valid result is not hidden or generalized as a universal schema-savings claim.

On the frozen Phase 4.5/4.6 corpus, dynamic retrieval policies retained about 98% all-required recall by failing open to the full catalog frequently; median tokens avoided was zero. Dense and hybrid retrieval did not improve the safety–selectivity frontier. Retrieval therefore remains RESEARCH_ONLY.

External ToolRet validation was attempted but not completed within the declared CPU/resource budget; no ToolRet metric is claimed. See the checked-in Phase 4 report, Phase 4.5 report, and Phase 4.6 report.

Availability

v0.5.0 ships a Python package only. There is no published @llmslim/core npm package, Rust engine, or WASM runtime. Those remain future possibilities, not current product capabilities.

Release and security information

See CHANGELOG.md, release notes, and SECURITY.md. Report vulnerabilities privately as described in the security policy.

License

MIT. See LICENSE.