Metadata-Version: 2.4
Name: llmslim
Version: 0.5.0
Summary: Cut your LLM prompt size by 40-70% in one line of code -- semantic chunking + extractive summarization that preserves meaning, instructions, and key entities.
Author-email: Yashvardhan Thanvi <thanatos9404@users.noreply.github.com>
License-Expression: MIT
Project-URL: Homepage, https://www.llmslim.app
Project-URL: Documentation, https://www.llmslim.app
Project-URL: Repository, https://github.com/Thanatos9404/llmslim
Project-URL: Bug Tracker, https://github.com/Thanatos9404/llmslim/issues
Keywords: llm,prompt-engineering,token-optimization,rag,nlp,summarization,openai,anthropic,gemini,context-window,cost-optimization
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Requires-Dist: scikit-learn>=1.0
Requires-Dist: jsonschema>=4.18
Provides-Extra: semantic
Requires-Dist: sentence-transformers>=2.2; extra == "semantic"
Provides-Extra: mcp
Requires-Dist: mcp<3,>=2.0; python_version >= "3.10" and extra == "mcp"
Provides-Extra: agents
Requires-Dist: openai-agents<1,>=0.11; python_version >= "3.10" and extra == "agents"
Requires-Dist: mcp<3,>=2.0; python_version >= "3.10" and extra == "agents"
Provides-Extra: fast-tokens
Requires-Dist: tiktoken>=0.5; extra == "fast-tokens"
Provides-Extra: nlp
Requires-Dist: nltk>=3.8; extra == "nlp"
Provides-Extra: structured
Requires-Dist: pyyaml>=6.0; extra == "structured"
Provides-Extra: all
Requires-Dist: sentence-transformers>=2.2; extra == "all"
Requires-Dist: mcp<3,>=2.0; python_version >= "3.10" and extra == "all"
Requires-Dist: openai-agents<1,>=0.11; python_version >= "3.10" and extra == "all"
Requires-Dist: tiktoken>=0.5; extra == "all"
Requires-Dist: nltk>=3.8; extra == "all"
Requires-Dist: pyyaml>=6.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff==0.15.21; extra == "dev"
Dynamic: license-file

# 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

```bash
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

```python
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](SECURITY.md) for the provenance
boundary applied to `ContextRole` values.

## Stable tool-contract APIs

Import stable tool-contract APIs from `llmslim.tools`:

```python
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](docs/tool-apis.md) 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.

```python
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](docs/phase-5/IMPLEMENTATION_REPORT.md).

## Experimental tool retrieval — research only

```python
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](docs/tool-apis.md#experimental-tool-retrieval).

## 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](docs/phase-4/BENCHMARK_REPORT.md),
[Phase 4.5 report](docs/phase-4.5/BENCHMARK_REPORT.md), and
[Phase 4.6 report](docs/phase-4.6/BENCHMARK_REPORT.md).

## 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](CHANGELOG.md), [release notes](release_notes.md), and
[SECURITY.md](SECURITY.md). Report vulnerabilities privately as described in
the security policy.

## License

MIT. See [LICENSE](LICENSE).
