Metadata-Version: 2.4
Name: generic-ml-cache-core
Version: 0.8.0
Summary: Hexagonal core library for generic-ml-cache: domain, use cases, ports, and the default outbound adapters (SQLite repo, blob store, local clients, API). Stateless; inject the data source.
Project-URL: Homepage, https://github.com/danielslobozian/generic-ml-cache
Project-URL: Repository, https://github.com/danielslobozian/generic-ml-cache
Project-URL: Issues, https://github.com/danielslobozian/generic-ml-cache/issues
Project-URL: Changelog, https://github.com/danielslobozian/generic-ml-cache/blob/main/CHANGELOG.md
Author: Daniel Slobozian
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: ai,cache,hexagonal,library,llm,ports-and-adapters,replay
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
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: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: coverage>=7; extra == 'dev'
Requires-Dist: cryptography>=42; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.15; extra == 'dev'
Requires-Dist: vulture>=2; extra == 'dev'
Provides-Extra: encryption
Requires-Dist: cryptography>=42; extra == 'encryption'
Description-Content-Type: text/markdown

<p align="center">
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/danielslobozian/generic-ml-cache/main/docs/images/gmlcache-mark-dark.png">
  <img src="https://raw.githubusercontent.com/danielslobozian/generic-ml-cache/main/docs/images/gmlcache-mark.png" alt="gmlcache" width="72">
</picture>
</p>

# generic-ml-cache-core

#### The hexagonal engine behind gmlcache — embeddable and stateless

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-2563eb?style=flat-square)](https://github.com/danielslobozian/generic-ml-cache/blob/main/LICENSE)
[![Status: Alpha](https://img.shields.io/badge/Status-Alpha-d97706?style=flat-square)](https://github.com/danielslobozian/generic-ml-cache/blob/main/docs/ROADMAP.md)

The reusable **engine** behind
[`gmlcache`](https://github.com/danielslobozian/generic-ml-cache/tree/main/packages/cli):
record a real ML client (or API) call once, replay it by its content key. It contains
the domain model, the use cases, the port contracts, **and the default outbound
adapters** (SQLite execution repository, filesystem blob store, the
claude/codex/cursor client runner, the API client, metrics, clock, fingerprinting) —
plus the `build_use_cases` composition factory.

Pure Python and **stateless**: it bakes in *structure*
(table names, blob naming, schema) but no *location* — you inject the data source.

> **Part of a single-user, local tool — not a gateway.** gmlcache records and replays across
> the subscriptions and APIs you already hold; it is **not** a multi-user router. See
> [Positioning](https://github.com/danielslobozian/generic-ml-cache/blob/main/docs/design/positioning.md).

## Install

```bash
pip install generic-ml-cache-core
```

## Embed it

Hand the library a data source and it wires the engine for you:

```python
from generic_ml_cache_core import build_use_cases
from generic_ml_cache_core.application.port.inbound.run_managed_local_execution_command import (
    RunManagedLocalExecutionCommand,
)

wired = build_use_cases(store_root="/path/you/choose")   # you provide the data source
command = RunManagedLocalExecutionCommand(
    client="claude", model="sonnet", effort="", context="", prompt="…",
)
execution = wired.run_managed.execute(command)           # records on a miss, replays on a hit
```

You reuse the shipped adapters by injecting a data source — you never reimplement them
(the **Spring Batch** model: the framework ships the writers, you provide the
connection). Need a different store? Construct the use cases yourself against the
ports and pass your own adapter.

## What's inside

- **Domain model** — executions, polymorphic call identities, artifacts, usage.
- **Use cases** — managed-local / passthrough / API runs, and probe (check).
- **Ports** (`application/port/...`) — client runner, blob store, execution repository,
  metrics, clock, fingerprint, API client.
- **Default adapters** (`adapter/out/...`) + the `build_use_cases` composition factory.
- **`generic_ml_cache_core.testing.InMemoryExecutionRepository`** — an in-memory
  reference adapter to test your code against the ports.

Inbound drivers —
[`gmlcache`](https://github.com/danielslobozian/generic-ml-cache/tree/main/packages/cli)
today, a daemon later — map their surface (a terminal, a REST API) onto these public
APIs; the core itself has no UI and reads no config file.

## Links

- **Repository & docs:** <https://github.com/danielslobozian/generic-ml-cache>
- **Changelog** (both packages, versioned in lockstep): [`CHANGELOG.md`](https://github.com/danielslobozian/generic-ml-cache/blob/main/CHANGELOG.md)
- **Security policy:** [`SECURITY.md`](https://github.com/danielslobozian/generic-ml-cache/blob/main/SECURITY.md)

## License

Apache-2.0 — see [`LICENSE`](https://github.com/danielslobozian/generic-ml-cache/blob/main/LICENSE)
and [`NOTICE`](https://github.com/danielslobozian/generic-ml-cache/blob/main/NOTICE).
