Metadata-Version: 2.4
Name: thinkery-leanctx-sdk
Version: 1.1.0
Summary: The Context SDK for AI Agents
Home-page: https://github.com/Thinkery-AG/leanctx-sdk
Author: Thinkery AG
License: Other/Proprietary License
Project-URL: Documentation, https://github.com/Thinkery-AG/leanctx-sdk#readme
Project-URL: Source, https://github.com/Thinkery-AG/leanctx-sdk
Project-URL: Issues, https://github.com/Thinkery-AG/leanctx-sdk/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: COMMERCIAL-LICENSE.md
License-File: THIRD_PARTY_NOTICES
Provides-Extra: agent
Requires-Dist: thinkery-leanctx-engine==3.10.1; extra == "agent"
Provides-Extra: agent-cuda
Requires-Dist: thinkery-leanctx-engine-cuda==3.10.1; (platform_system == "Linux" and platform_machine == "x86_64") and extra == "agent-cuda"
Provides-Extra: agent-windows-gnu
Requires-Dist: thinkery-leanctx-engine-windows-gnu==3.10.1; (platform_system == "Windows" and platform_machine == "AMD64") and extra == "agent-windows-gnu"
Provides-Extra: openai-agents
Requires-Dist: openai-agents==0.8.4; python_version >= "3.10" and extra == "openai-agents"
Requires-Dist: openai==2.19.0; python_version >= "3.10" and extra == "openai-agents"
Requires-Dist: pydantic==2.12.3; python_version >= "3.10" and extra == "openai-agents"
Requires-Dist: requests==2.33.0; python_version >= "3.10" and extra == "openai-agents"
Requires-Dist: urllib3==2.7.0; python_version >= "3.10" and extra == "openai-agents"
Dynamic: license-file

# LeanCTX SDK

Build Python, TypeScript, Go, Rust, JVM, and .NET coding agents that read,
search, edit, and run approved commands without sending raw repository output
to the model every time.

Your framework owns the model and agent loop. LeanCTX owns the local context
tools, compression, cache, permissions, token measurements, and recovery path.

## Choose the right product

| You want to… | Use |
| --- | --- |
| improve an existing coding agent through CLI/MCP | LeanCTX Engine |
| build your own agent with LeanCTX tools | LeanCTX SDK + Engine |
| keep your own model/framework but add governed context | `AgentContext` |

The SDK does not contain a second implementation of the Engine. It starts one
verified local Engine process and exposes its negotiated capabilities as stable
language-native methods.

```text
your model / agent loop
          ↓
AgentContext or AsyncAgentContext
          ↓  versioned local Agent Tools Interface
LeanCTX Engine 3.10.1
          ↓
project-jailed files, cache, search, patches, approved commands
```

## Install

Engine 3.10.1 and its companion wheels are published and cryptographically
bound by the SDK release gate. Install the Python SDK and Engine together with:

Standard Engine:

```bash
python -m pip install "thinkery-leanctx-sdk[agent]==1.1.0"
```

With the certified OpenAI Agents integration:

```bash
python -m pip install "thinkery-leanctx-sdk[agent,openai-agents]==1.1.0"
```

CUDA and Windows-GNU builds use the documented `agent-cuda` and
`agent-windows-gnu` extras. The core SDK remains pure Python.

## Language SDKs

All SDK 1.1 previews implement the five stable Product primitives, Engine
Interface v1, and PR #8 Agent Tools 1.1 contract. Engine 3.10.1 satisfies their
runtime dependency; non-Python registry publication remains a separate gate.

| Runtime | Package source | Package identity |
| --- | --- | --- |
| Python 3.9–3.14 | repository root | `thinkery-leanctx-sdk` |
| Node.js 22+ / TypeScript | `packages/typescript` | `@thinkery-ag/leanctx-sdk` |
| Go 1.24+ | `packages/go` | `github.com/Thinkery-AG/leanctx-sdk-go` |
| Rust 1.76+ | `packages/rust` | `thinkery-leanctx-sdk` |
| Java 21 / Kotlin 2.1 | `packages/jvm` | `com.thinkery.leanctx:leanctx-sdk` |
| .NET 8+ | `packages/dotnet` | `Thinkery.LeanCtx` |

Each package includes language-native tests against the same canonical
serialization fixture, strict protocol validation, explicit execution policy,
package-content checks, and source-available license notices. The release
workflow requires every language job before pull-request validation or
publication provenance can pass. The Engine remains a separate local binary.

## Five-minute custom agent

```python
from leanctx_sdk import AgentContext


def my_model(task: str, context: str) -> str:
    # Replace with any model or framework call.
    return f"{task}\n\nRelevant project context:\n{context}"


with AgentContext(".", task="Explain the public API") as ctx:
    files = ctx.tree(depth=2)
    matches = ctx.search("class AgentContext", path="src")
    source = ctx.read("src/leanctx_sdk/agent.py", mode="signatures")
    answer = my_model(ctx.task, "\n".join((files.text, matches.text, source.text)))
    print(answer)
    print(f"saved tokens: {ctx.metrics.saved_tokens}")
```

Default permissions are read-only. A coding agent must opt in explicitly:

```python
from leanctx_sdk import AgentContext, AgentPermissions, ExecutionPolicy

with AgentContext(
    ".",
    permissions=AgentPermissions(write=True, execute=True),
    execution_policy=ExecutionPolicy(allowed_executables=("git", "pytest")),
) as ctx:
    ctx.replace_unique("app.py", "old_name", "new_name")
    tests = ctx.run(("pytest", "-q"), timeout=30)
```

The permission policy is immutable for the session and is enforced again by
the Engine. `call()` cannot bypass it, and process tools must use `run(argv)`.

## SDK 1.1 Agent Tools capabilities

- `read`, `search`, `glob`, `tree`, `compose`, and `symbol`
- safe `create_file`, `patch`, and `replace_unique`
- allowlisted argv execution with compressed output
- persistent per-agent cache and aggregate token measurements
- synchronous and asynchronous APIs
- capability negotiation and typed fail-closed errors
- optional OpenAI Agents 0.8.4 function tools

The SDK supplies the tool substrate, not an autonomous planner, model, hosted
service, or universal quality guarantee. Savings are measured per call against
the Engine's raw-output baseline; they are not a promise for every workload.

## Compatibility

The five SDK 1.0 lifecycle primitives remain available unchanged:
`ContextSession`, `ContextSource`, `ContextView`, `ContextPlan`, and
`ContextReceipt`. `AgentContext` requires Agent Tools Interface v1 from Engine
3.10.1; the older context-view/recover Engine Interface v1 remains unchanged.

See:

- [Custom agents](docs/CUSTOM-AGENTS.md)
- [Quickstart](docs/QUICKSTART.md)
- [Compatibility](COMPATIBILITY.md)
- [Security](SECURITY.md)
- [Errors](docs/ERRORS.md)
- [Migration](MIGRATION.md)
- [Stable public surface](PUBLIC-SURFACE-MANIFEST.md)

## License

LeanCTX SDK is source-available. Commercial Production Use, OEM embedding, and
commercial redistribution require a written agreement with Thinkery AG.
LeanCTX Engine and its companion binary distributions remain Apache-2.0.
