Metadata-Version: 2.4
Name: llm-kelt
Version: 0.4.0
Summary: Framework for collecting and managing LLM context
Author-email: LLM Works LLC <info@llm-works.ai>
License: Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: appinfra>=0.8
Requires-Dist: sqlalchemy<3.0,>=2.0
Requires-Dist: sqlalchemy-utils<1.0,>=0.42
Requires-Dist: psycopg2-binary<3.0,>=2.9
Requires-Dist: pgvector<1.0,>=0.3
Requires-Dist: alembic<2.0,>=1.12
Requires-Dist: llm-infer<1.0,>=0.2.0
Requires-Dist: llm-saia<1.0,>=0.2.0
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: fastapi<1.0,>=0.109
Requires-Dist: uvicorn<1.0,>=0.27
Provides-Extra: dev
Requires-Dist: coverage<8.0.0,>=7.0.0; extra == "dev"
Requires-Dist: ruff<1.0.0,>=0.1.0; extra == "dev"
Requires-Dist: mypy<2.0.0,>=1.0.0; extra == "dev"
Requires-Dist: pytest<10.0.0,>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio<1.0,>=0.21; extra == "dev"
Requires-Dist: pytest-cov<8.0.0,>=4.0.0; extra == "dev"
Requires-Dist: pytest-xdist<4.0.0,>=3.0.0; extra == "dev"
Provides-Extra: training
Requires-Dist: torch>=2.2; extra == "training"
Requires-Dist: transformers>=4.40; extra == "training"
Requires-Dist: peft>=0.10; extra == "training"
Requires-Dist: trl>=0.12; extra == "training"
Requires-Dist: datasets>=2.18; extra == "training"
Requires-Dist: accelerate>=0.28; extra == "training"
Requires-Dist: bitsandbytes>=0.43; extra == "training"
Dynamic: license-file

# llm-kelt

*Knowledge · Embedding · Learning · Training*

![Python](https://img.shields.io/badge/python-3.11+-blue.svg)
![Type Hints](https://img.shields.io/badge/type%20hints-100%25-brightgreen.svg)
[![Linting: Ruff](https://img.shields.io/badge/linting-ruff-yellowgreen)](https://github.com/astral-sh/ruff)
[![CI](https://github.com/llm-works/llm-kelt/actions/workflows/ci.yml/badge.svg)](https://github.com/llm-works/llm-kelt/actions/workflows/ci.yml)
![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)

Persistent memory and fine-tuning data for LLM applications, backed by Postgres.

Store the things an LLM needs to know or learn from — facts, feedback, preferences, predictions,
directives — under an isolation key. Retrieve them for prompt injection or RAG. Export them to
DPO/SFT/classifier datasets. Train LoRA/DPO/Prompt adapters from the exported data.

## Requirements

- Python 3.11+
- PostgreSQL 16+ with the `vector` extension (pgvector)
- For training: CUDA GPU (or MPS on Apple Silicon)

## Install

```bash
pip install llm-kelt              # runtime
pip install llm-kelt[training]    # + torch / transformers / peft / trl
```

## Minimal example

```python
from appinfra.config import Config
from appinfra.log import LogConfig, LoggerFactory
from llm_kelt import ClientContext, ClientFactory
from llm_kelt.inference import ContextBuilder

config = Config("etc/llm-kelt.yaml")
lg = LoggerFactory.create_root(LogConfig.from_params(level="warning"))

kelt = ClientFactory(lg).create_from_config(
    context=ClientContext(context_key="my-agent"),
    config=config,
)

kelt.atomic.assertions.add("Timezone: UTC", category="settings")
kelt.atomic.assertions.add("Prefers concise, code-first answers", category="style")

system_prompt = ContextBuilder(kelt.atomic.assertions).build_system_prompt(
    base_prompt="You are a helpful assistant.",
)
# → "You are a helpful assistant.\n\n## About the user:\n- Timezone: UTC\n- ..."
```

That's the whole shape: put things in under a `context_key`, pull them back out grouped for
prompt injection. Everything else (RAG, feedback, preferences, training) builds on the same
model.

## Where to go next

- [Quickstart](docs/quickstart.md) — 5 minutes from install to first RAG query.
- [Concepts](docs/concepts.md) — context keys, schemas, atomic vs KG. Read once before the tutorials.
- [Atomic memory](docs/atomic-memory.md) — the seven fact clients (assertions, feedback,
  preferences, predictions, directives, interactions, solutions) and how they relate.
- [Context & RAG](docs/context-and-rag.md) — embedding facts, semantic search, `ContextQuery`.
- [Conversation](docs/conversation.md) — multi-turn sessions, token accounting, compaction, storage.
- [Training](docs/training.md) — manifest workflow, LoRA/DPO/SFT/Prompt, exports, adapter registry.
- [Knowledge graph](docs/knowledge-graph.md) — entities, aliases, hierarchical scopes.
- [Multi-schema](docs/multi-schema.md) — `SchemaMode`, `with_schema()`, isolation.
- [CLI reference](docs/cli.md) — `kelt atomic|proxy|train|session`.
- [Glossary](docs/glossary.md) — project-specific terms.

## Configuration

The library reads its config from `etc/llm-kelt.yaml`. Key sections:

```yaml
dbs:
  main:
    url: postgresql://user:pass@localhost:5432/llm_kelt
    extensions: [vector]

llm:
  default_backend: local
  backends:
    local:
      base_url: http://localhost:8000/v1
      model: default

embedding:
  type: openai
  base_url: http://localhost:8001/v1
  model: text-embedding-3-small

kelt:
  adapters:
    lora:
      base_path: ~/models/adapters
```

`llm`, `embedding`, and `kelt.adapters` are only required for the subsystems that use them
(`ContextQuery`, RAG, and training respectively).

## Examples

Runnable scripts in [`examples/`](examples/):

- `01_facts_and_context.py` — assertions + `ContextBuilder`.
- `02_rag_retrieval.py` — embeddings, `search_similar`, `ContextQuery` with RAG.
- `03_training_export.py` — feedback + preferences → DPO/SFT/classifier JSONL.
- `04_lora_training.py` — end-to-end LoRA training.
- `05_conversation.py` — `Conversation`, compaction, `FileSessionStorage`.

## License

Apache 2.0
