Metadata-Version: 2.4
Name: protoprompt
Version: 0.6.0
Summary: Layered context builder for LLM prompts: RAG + compressed session memory + user profile
Author: EnergoAI Hub
Maintainer: EnergoAI Hub
License-Expression: MIT
Project-URL: Homepage, https://github.com/Idxeed/protoprompt
Project-URL: Documentation, https://idxeed.github.io/protoprompt/
Project-URL: Source, https://github.com/Idxeed/protoprompt
Project-URL: Issues, https://github.com/Idxeed/protoprompt/issues
Project-URL: Changelog, https://github.com/Idxeed/protoprompt/blob/master/CHANGELOG.md
Keywords: llm,rag,prompt,context,embedding
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: chroma
Requires-Dist: chromadb<2,>=1.5; extra == "chroma"
Provides-Extra: tiktoken
Requires-Dist: tiktoken>=0.5; extra == "tiktoken"
Provides-Extra: http
Requires-Dist: httpx>=0.27; extra == "http"
Provides-Extra: ollama
Requires-Dist: httpx>=0.27; extra == "ollama"
Provides-Extra: openai
Requires-Dist: openai>=1.40; extra == "openai"
Provides-Extra: qdrant
Requires-Dist: qdrant-client>=1.12; extra == "qdrant"
Provides-Extra: fastembed
Requires-Dist: fastembed>=0.4; extra == "fastembed"
Provides-Extra: local
Requires-Dist: sentence-transformers>=3.0; extra == "local"
Provides-Extra: secrets
Requires-Dist: cryptography>=42; extra == "secrets"
Requires-Dist: keyring>=24; extra == "secrets"
Provides-Extra: mcp
Requires-Dist: mcp<3,>=2; extra == "mcp"
Provides-Extra: agents
Requires-Dist: openai-agents<0.23,>=0.22; extra == "agents"
Provides-Extra: langgraph
Requires-Dist: langgraph<1.3,>=1.2; extra == "langgraph"
Provides-Extra: telegram
Requires-Dist: aiogram<4,>=3.31; extra == "telegram"
Provides-Extra: postgres
Requires-Dist: psycopg[binary,pool]<3.4,>=3.3; extra == "postgres"
Provides-Extra: otel
Requires-Dist: opentelemetry-sdk<2,>=1.44; extra == "otel"
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2,>=1.44; extra == "otel"
Provides-Extra: redis
Requires-Dist: redis<9,>=8.1; extra == "redis"
Provides-Extra: anthropic
Requires-Dist: anthropic<2,>=1; extra == "anthropic"
Provides-Extra: google
Requires-Dist: google-genai<3,>=2.20; extra == "google"
Provides-Extra: bedrock
Requires-Dist: boto3<2,>=1.43; extra == "bedrock"
Provides-Extra: aws-secrets
Requires-Dist: boto3<2,>=1.43; extra == "aws-secrets"
Provides-Extra: gcp-secrets
Requires-Dist: google-cloud-secret-manager<3,>=2.30; extra == "gcp-secrets"
Provides-Extra: fastapi
Requires-Dist: fastapi<1,>=0.141; extra == "fastapi"
Requires-Dist: uvicorn<1,>=0.52; extra == "fastapi"
Provides-Extra: pydanticai
Requires-Dist: pydantic-ai-slim<3,>=2.35; extra == "pydanticai"
Provides-Extra: llamaindex
Requires-Dist: llama-index-core<0.15,>=0.14; extra == "llamaindex"
Provides-Extra: documents
Requires-Dist: pypdf<7,>=6.16; extra == "documents"
Requires-Dist: python-docx<2,>=1.2; extra == "documents"
Requires-Dist: beautifulsoup4<5,>=4.14; extra == "documents"
Provides-Extra: elasticsearch
Requires-Dist: elasticsearch[async]<10,>=9.5; extra == "elasticsearch"
Provides-Extra: opensearch
Requires-Dist: opensearch-py[async]<3.2,>=3.1; extra == "opensearch"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: pytest-socket<1,>=0.7; extra == "dev"
Requires-Dist: mkdocs>=1.5; extra == "dev"
Requires-Dist: mkdocs-material>=9; extra == "dev"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Requires-Dist: openai>=1.40; extra == "dev"
Requires-Dist: cryptography>=42; extra == "dev"
Requires-Dist: keyring>=24; extra == "dev"
Requires-Dist: mcp<3,>=2; extra == "dev"
Requires-Dist: openai-agents<0.23,>=0.22; extra == "dev"
Requires-Dist: langgraph<1.3,>=1.2; extra == "dev"
Requires-Dist: aiogram<4,>=3.31; extra == "dev"
Requires-Dist: pillow<13,>=12; extra == "dev"
Requires-Dist: psycopg[binary,pool]<3.4,>=3.3; extra == "dev"
Requires-Dist: opentelemetry-sdk<2,>=1.44; extra == "dev"
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2,>=1.44; extra == "dev"
Requires-Dist: redis<9,>=8.1; extra == "dev"
Requires-Dist: fakeredis<3,>=2.31; extra == "dev"
Requires-Dist: anthropic<2,>=1; extra == "dev"
Requires-Dist: google-genai<3,>=2.20; extra == "dev"
Requires-Dist: boto3<2,>=1.43; extra == "dev"
Requires-Dist: google-cloud-secret-manager<3,>=2.30; extra == "dev"
Requires-Dist: fastapi<1,>=0.141; extra == "dev"
Requires-Dist: uvicorn<1,>=0.52; extra == "dev"
Requires-Dist: pydantic-ai-slim<3,>=2.35; extra == "dev"
Requires-Dist: llama-index-core<0.15,>=0.14; extra == "dev"
Requires-Dist: pypdf<7,>=6.16; extra == "dev"
Requires-Dist: python-docx<2,>=1.2; extra == "dev"
Requires-Dist: beautifulsoup4<5,>=4.14; extra == "dev"
Requires-Dist: elasticsearch[async]<10,>=9.5; extra == "dev"
Requires-Dist: opensearch-py[async]<3.2,>=3.1; extra == "dev"
Dynamic: license-file

# protoprompt

[![CI](https://github.com/Idxeed/protoprompt/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/Idxeed/protoprompt/actions/workflows/ci.yml)
[![Python 3.11–3.13](https://img.shields.io/badge/python-3.11%E2%80%933.13-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)

**Контекстный движок для LLM-приложений:** RAG, память диалога, профиль
пользователя и строгий токен-бюджет через единый Python API.

[Документация](https://idxeed.github.io/protoprompt/ru/) ·
[English](README.en.md) ·
[Примеры](examples/) ·
[Каталог интеграций](INTEGRATIONS.md) ·
[Roadmap](ROADMAP.md) ·
[Как добавить интеграцию](CONTRIBUTING.md) ·
[Changelog](CHANGELOG.md)

> Проект находится в alpha-стадии. Публичный API уже покрыт тестами, но до
> версии 1.0 возможны изменения контрактов.

![Telegram-бот вспоминает старый факт и показывает provenance](docs/assets/telegram-memory.gif)

Эталонный [Telegram-бот](docs/ru/telegram.md) сохраняет длинную память в
SQLite, работает с OpenAI или Ollama и объясняет каждый recall через `/why`.

## Что решает protoprompt

LLM обычно нужна не просто история чата, а несколько разных видов контекста:
найденные документы, важные факты из прошлых сессий, профиль пользователя и
исходный system prompt. Если собирать всё вручную, логика поиска, приоритетов и
обрезки быстро расползается по приложению.

`protoprompt` собирает эти слои в одном месте и возвращает не только готовый
промпт, но и provenance — какие RAG-чанки, блоки памяти и данные профиля были
использованы.

| Возможность | Что входит |
|---|---|
| RAG | чанкинг, индексация, top-k поиск, фильтры, reranking и provenance |
| Память сессии | эвристическое или LLM-сжатие длинных диалогов |
| Профиль | извлечение, merge, optimistic locking и SQLite-хранилище |
| Токен-бюджет | жёсткий лимит, приоритеты слоёв и отчёт об обрезке |
| Хранилища | in-memory, SQLite, ChromaDB, Qdrant, pgvector, Elasticsearch/OpenSearch и Redis services |
| LLM и embeddings | OpenAI, Anthropic, Google GenAI, Bedrock, Ollama и локальные модели |
| Секреты | encrypted SQLite, AWS Secrets Manager и GCP Secret Manager |
| Connectivity | MCP, OpenAI Agents SDK, LangGraph, PydanticAI, LlamaIndex, aiogram 3 и FastAPI |
| Данные | bounded readers для text/source/HTML/PDF/DOCX и framework converters |

Ядро не имеет обязательных сторонних зависимостей. Интеграции подключаются
через extras и не импортируются, пока не понадобятся.

## Установка

```bash
pip install protoprompt

# Частые варианты
pip install "protoprompt[openai,tiktoken]"
pip install "protoprompt[ollama]"
pip install "protoprompt[chroma]"
pip install "protoprompt[qdrant]"
pip install "protoprompt[local]"       # sentence-transformers
pip install "protoprompt[fastembed]"
pip install "protoprompt[secrets]"
pip install "protoprompt[mcp]"
pip install "protoprompt[agents]"
pip install "protoprompt[langgraph]"
pip install "protoprompt[telegram,ollama]"
pip install "protoprompt[anthropic]"
pip install "protoprompt[google]"
pip install "protoprompt[bedrock]"
pip install "protoprompt[pydanticai]"
pip install "protoprompt[llamaindex]"
pip install "protoprompt[postgres,redis,otel]"
pip install "protoprompt[elasticsearch]"  # или opensearch
pip install "protoprompt[documents,fastapi]"
pip install "protoprompt[aws-secrets]"    # или gcp-secrets
```

Для работы из текущей ветки:

```bash
pip install "protoprompt @ git+https://github.com/Idxeed/protoprompt.git@master"
```

Требуется Python 3.11 или новее.

## Быстрый старт

Пример полностью локальный: сеть, API-ключ и сторонняя векторная БД не нужны.

```python
import asyncio

from protoprompt import ContextBuilder, ContextInput, InMemStore


class DemoLLM:
    async def embed(self, texts, model=""):
        # В приложении замените на OpenAIClient, OllamaClient
        # или локальный embedding-клиент.
        return [[1.0, 0.0] for _ in texts]

    async def chat(self, messages, model="", **options):
        return "demo"


async def main():
    llm = DemoLLM()
    store = InMemStore()
    chunks = [
        "protoprompt объединяет RAG, память сессии и профиль пользователя.",
        "Токеновый бюджет не позволяет итоговому контексту превысить лимит.",
    ]
    store.add("guide", chunks, await llm.embed(chunks))

    builder = ContextBuilder(store, llm)
    messages = await builder.build_messages(
        ContextInput(
            query="Что умеет protoprompt?",
            system_prompt="Отвечай кратко и только по контексту.",
            doc_ids=["guide"],
            include_session=False,
        ),
        user_message="Что умеет protoprompt?",
    )

    print(messages)  # готовый OpenAI-style список system + user


asyncio.run(main())
```

Более реалистичные рецепты находятся в [`examples/`](examples/): Ollama RAG,
OpenAI с токен-бюджетом, локальные embeddings, сжатие сессии, профиль и
зашифрованный vault.

## Как устроена сборка контекста

```text
запрос ─┬─> RAG по документам ───────┐
        ├─> память текущей сессии ───┤
        ├─> профиль пользователя ────┼─> ContextBuilder ─> ContextOutput
        └─> исходный system prompt ──┘          │
                                                └─ provenance + budget report
```

Основные контракты намеренно небольшие:

- `StoreProtocol` / `AsyncStoreProtocol` — синхронное или асинхронное
  векторное хранилище;
- `LLMClientProtocol` — `chat()` и `embed()`;
- `StrategyProtocol` — стратегия сжатия диалога;
- `TokenCounter` — подсчёт токенов для конкретной модели.

Благодаря этому встроенные адаптеры можно заменить своими без переписывания
сборщика контекста.

## Основные точки входа

```python
from protoprompt import (
    ContextBuilder,
    TokenBudgetedContextBuilder,
    Pipeline,
    ProfileManager,
    InMemStore,
    SqliteStore,
)

from protoprompt.rag import DocumentIndexer, Retriever
from protoprompt.secrets import EncryptedSqliteSecretStore, SecretAccess
from protoprompt.integrations import OpenAIClient, OllamaClient, QdrantStore
```

Полный API и подробные руководства:

- [быстрый старт](https://idxeed.github.io/protoprompt/ru/quickstart/);
- [RAG](https://idxeed.github.io/protoprompt/ru/rag/);
- [память и сжатие](https://idxeed.github.io/protoprompt/ru/concepts/compression/);
- [профиль пользователя](https://idxeed.github.io/protoprompt/ru/profile/);
- [секреты](https://idxeed.github.io/protoprompt/ru/secrets/);
- [интеграции](https://idxeed.github.io/protoprompt/ru/integrations/).

## Экспериментальный coding-agent

В монорепозитории есть CLI поверх `protoprompt.agent.WorkingMemory`:

```bash
pip install -e "apps/agent-cli[ollama]"
pp-agent /path/to/project
```

Он поддерживает сессии, hot/cold memory, план-режим и подтверждение опасных
инструментов. Подробнее — в [`apps/agent-cli/README.md`](apps/agent-cli/README.md).

## Разработка

```bash
git clone https://github.com/Idxeed/protoprompt.git
cd protoprompt
python -m venv .venv

# Windows
.venv\Scripts\activate

# Linux / macOS
source .venv/bin/activate

pip install -e ".[chroma,qdrant,dev]"
pytest
python scripts/build_docs.py --clean
```

CI проверяет Python 3.11–3.13, интеграционные тесты, CLI, содержимое wheel и
обе строгие сборки документации.

## Лицензия

[MIT](LICENSE)
