Simple OKF Template

Локальный шаблон и MCP-инструменты для ведения agent-readable knowledge bundle в Open Knowledge Format.

Что это

Короче: клонируешь и запускаешь в своём AI-окружении. Я использую Pi.

Есть навык (skill): вызываешь его и можешь в правильном формате создавать документы, собирать контекст и искать через MCP.

В MCP есть команды для дискретных действий и поиска по RAG.

RAG помогает искать по ID и содержанию. Это особенно полезно, если запускать субагентов и для каждого прохода вытаскивать контекст документов.

Локальный запуск

Требования

Python 3.10+
uv
make — опционально, но удобнее для типовых команд

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

git clone git@github.com:18studio/simple_okf.git
cd simple_okf
PY='uv run python' make init

make init установит зависимости через uv, создаст локальный .env из примера, проверит OKF-бандл и обновит локальный RAG-индекс.

Почему PY='uv run python': команды проекта зависят от Python-пакетов из uv-окружения. Голый python3 -m okf_mcp ... может не увидеть зависимости вроде typer, если виртуальное окружение не активировано.

Если make не нужен, те же шаги можно выполнить вручную:

uv sync
test -f .env || cp .env.example .env
uv run python -m okf_mcp validate okf
uv run python -m okf_mcp rag inspect --env .env --pretty
uv run python -m okf_mcp rag refresh --env .env --pretty

Что делать дальше

После быстрого старта есть три основных сценария:

Вести знания в OKF — редактируйте Markdown-концепты в okf/, затем запускайте validate/index/graph.
Искать и отвечать через RAG — обновляйте локальный RAG-индекс и задавайте вопросы по OKF-бандлу.
Подключить агентов через MCP — запустите MCP-сервер или используйте готовый сервер simple-okf из .mcp.json.

Минимальный ежедневный цикл:

# 1. После правок в okf/
uv run python -m okf_mcp validate okf
uv run python -m okf_mcp indexes okf
uv run python -m okf_mcp graph okf --out artifacts/okf/graph.json --html-out artifacts/okf/graph.html

# 2. Обновить локальный RAG-индекс
uv run python -m okf_mcp rag refresh --env .env --pretty

# 3. Спросить по базе знаний
uv run python -m okf_mcp rag retrieve "what is OKF?" --env .env --answer --limit 3 --pretty

RAG: поиск и ответы

По умолчанию используется RAG_PROFILE=local: всё работает offline-first и не требует ClickHouse/OpenSearch/Qdrant.

Проверить, что RAG видит OKF-бандл:

uv run python -m okf_mcp rag inspect --env .env --pretty

Обновить локальный индекс:

uv run python -m okf_mcp rag refresh --env .env --pretty

Найти релевантные фрагменты:

uv run python -m okf_mcp rag retrieve "project requirements" --env .env --limit 5 --pretty

Получить extractive-ответ с цитатами:

uv run python -m okf_mcp rag retrieve "what is this repository for?" --env .env --answer --limit 3 --pretty

Проверить готовность локального RAG и свежесть индекса:

uv run python -m okf_mcp rag local-readiness --env .env --pretty
uv run python -m okf_mcp rag index-freshness --env .env --pretty

Запуск MCP-сервера

В RAG_PROFILE=local MCP-сервер стартует без live-инфраструктуры; локальные OKF/RAG команды остаются offline-first. Для RAG_PROFILE=production или при включённом RAG_ENABLE_PRODUCTION_STARTUP_READINESS=true убедитесь, что ClickHouse, OpenSearch и Qdrant доступны по URL из .env: startup readiness проверяет эти зависимости. Быстрее всего поднять их через docker compose up или скопировать .env.example в .env и заменить service-name URL на host-side 127.0.0.1.

Для stdio-транспорта:

uv run python -m okf_mcp server --bundle okf

Для HTTP-транспорта:

uv run python -m okf_mcp server --bundle okf --transport http --host 127.0.0.1 --port 8000

В Pi и других MCP-клиентах можно использовать готовую конфигурацию из .mcp.json: сервер называется simple-okf.

Запуск через Docker Compose

Если не хочется ставить Python/uv локально, можно поднять HTTP MCP-сервер через Docker Compose:

docker compose up --build

Сервис слушает http://127.0.0.1:8000. Compose также поднимает локальные ClickHouse, OpenSearch и Qdrant: MCP-сервер проверяет их готовность при старте и не начинает обслуживать запросы, если инфраструктура недоступна.

Compose загружает переменные из корневого .env через env_file. Создайте его из .env.example; значения в примере используют имена compose-сервисов (clickhouse, opensearch, qdrant). Для запуска CLI/MCP с хоста переопределите URL на 127.0.0.1.

Профили local, quality и production, backup/restore для Qdrant/OpenSearch/ClickHouse, index refresh rollback/swap, security/MCP exposure и CI matrix описаны в RAG/MCP Production Hardening Runbook.

Подключены локальные директории:

./okf → /app/okf
./artifacts → /app/artifacts

Остановить сервис:

docker compose down

Переменные окружения

Основной локальный env-файл для RAG — .env. Он создаётся из примера .env.example и не должен попадать в git:

cp .env.example .env

Если .env был создан до появления readiness-проверок, обновите его из примера или добавьте ключи RAG_CLICKHOUSE_*, RAG_OPENSEARCH_* и RAG_QDRANT_*; они требуются для production readiness-проверки. В RAG_PROFILE=local MCP-сервер стартует без live-инфраструктуры.

Для разового запуска RAG с другим env-файлом используйте флаг --env:

uv run python -m okf_mcp rag inspect --env /path/to/.env --pretty

Переменная	Где задаётся	Значение в `.env.example`	Описание
`OKF_BUNDLE`	shell env / Compose `env_file`	`okf`	Путь к OKF-бандлу для MCP-сервера, если не передан `--bundle`.
`RAG_BUNDLE_DIR`	`.env` / Compose `env_file`	`okf`	OKF-бандл, который RAG-инструменты инспектируют, индексируют и по которому ищут. Относительные пути считаются от корня репозитория при CLI-запуске и от `/app` при Docker Compose. Директория должна существовать.
`RAG_ARTIFACTS_DIR`	`.env` / Compose `env_file`	`artifacts/rag`	Директория для локальных RAG-артефактов. Должна резолвиться внутрь директории `artifacts/`.
`RAG_RETRIEVAL_RESULT_LIMIT`	`.env` / Compose `env_file`	`10`	Количество результатов по умолчанию для `rag retrieve`, если не передан `--limit`. Значение должно быть целым числом `>= 1`.
`RAG_ANSWER_EVIDENCE_LIMIT`	`.env` / Compose `env_file`	`5`	Количество фрагментов-доказательств для extractive-ответа RAG. Значение должно быть целым числом `>= 1`.
`RAG_PROFILE`	`.env` / Compose `env_file`	`local`	Профиль RAG: `local`, `quality` или `production`. `local` не требует live-инфраструктуры для CLI RAG.
`RAG_RETRIEVAL_MODE`	`.env` / Compose `env_file`	`local`	Режим retrieval: `local`, `keyword`, `semantic`, `hybrid`, `qdrant-hybrid` или `opensearch-hybrid`. `semantic` использует dense-only Qdrant; `qdrant-hybrid` требует feature flag и Qdrant sparse/prefetch capabilities; `opensearch-hybrid` откатывается к keyword/BM25, если `RAG_ENABLE_OPENSEARCH_PIPELINES=false`.
`RAG_CHUNKER_PROVIDER`	`.env` / Compose `env_file`	`local`	Провайдер chunking: deterministic `local`, optional Python `chonkie` или self-hosted `chonkie-rest`.
`RAG_CHUNKER_STRATEGY`	`.env` / Compose `env_file`	`heading-local`	Стратегия chunking: `heading-local` для local; `recursive`, `semantic` или `late` для Chonkie. При `RAG_ENABLE_CHONKIE=true` без явной стратегии используется `recursive`.
`RAG_CHUNKER_CONFIG`	`.env` / Compose `env_file`	`{}`	JSON-object или путь к JSON-файлу с параметрами chunker. Для `chonkie-rest` требуется `base_url`; secret-like keys, URL userinfo и query strings запрещены, потому что config попадает в index metadata.
`RAG_ENABLE_CHONKIE`	`.env` / Compose `env_file`	`false`	Feature flag для optional Chonkie. Установите `true` и поставьте extra `uv sync --extra chonkie` для Python adapter; при `false` используйте local provider.
`RAG_ALLOW_REMOTE_CHUNKING`	`.env` / Compose `env_file`	`false`	Явное разрешение отправлять OKF-текст в `chonkie-rest` из `RAG_PROFILE=local`; без него используйте `quality`/`production` профиль или локальный chunker.
`RAG_ENABLE_QDRANT_HYBRID`	`.env` / Compose `env_file`	`false`	Feature flag для режима `qdrant-hybrid`. При `false` используйте rollback на `RAG_RETRIEVAL_MODE=semantic` для dense-only Qdrant.
`RAG_ENABLE_OPENSEARCH_PIPELINES`	`.env` / Compose `env_file`	`false`	Feature flag для OpenSearch ingest/search pipelines. При `false` `opensearch-hybrid` сохраняет keyword/BM25 поведение и не требует pipeline config.
`RAG_ENABLE_PRODUCTION_STARTUP_READINESS`	`.env` / Compose `env_file`	`false`	Принудительно включает startup readiness-проверку ClickHouse/OpenSearch/Qdrant вне production-профиля.
`RAG_CLICKHOUSE_URL`	`.env` / Compose `env_file`	`http://clickhouse:8123`	ClickHouse HTTP endpoint for MCP startup readiness and future RAG/RAGAS event storage. Use `http://127.0.0.1:8123` from host-side runs.
`RAG_CLICKHOUSE_USER`	`.env` / Compose `env_file`	`default`	ClickHouse user.
`RAG_CLICKHOUSE_PASSWORD`	`.env` / Compose `env_file`	пусто	ClickHouse password; keep real secrets local-only.
`RAG_CLICKHOUSE_DATABASE`	`.env` / Compose `env_file`	`okf_rag`	Target ClickHouse database name for future event storage.
`RAG_CLICKHOUSE_EVENTS_TABLE`	`.env` / Compose `env_file`	`rag_events`	Target ClickHouse events table name for future event storage.
`RAG_OPENSEARCH_URL`	`.env` / Compose `env_file`	`http://opensearch:9200`	OpenSearch endpoint checked at MCP startup. Use `http://127.0.0.1:9200` from host-side runs.
`RAG_OPENSEARCH_USER`	`.env` / Compose `env_file`	пусто	Optional OpenSearch basic-auth user.
`RAG_OPENSEARCH_PASSWORD`	`.env` / Compose `env_file`	пусто	Optional OpenSearch basic-auth password; keep real secrets local-only.
`RAG_OPENSEARCH_INDEX`	`.env` / Compose `env_file`	`okf-concepts`	Target OpenSearch index name for keyword or pipeline retrieval.
`RAG_OPENSEARCH_INGEST_PIPELINE`	`.env` / Compose `env_file`	`okf-rag-ingest`	Ingest pipeline name used only for `opensearch-ingest-embedding` ownership.
`RAG_OPENSEARCH_SEARCH_PIPELINE`	`.env` / Compose `env_file`	`okf-rag-hybrid-search`	Search pipeline name required when `opensearch-hybrid` runs with `RAG_ENABLE_OPENSEARCH_PIPELINES=true`.
`RAG_OPENSEARCH_EMBEDDING_OWNERSHIP`	`.env` / Compose `env_file`	`external-embedding`	`external-embedding` means the app writes deterministic/test vectors; `opensearch-ingest-embedding` means OpenSearch `text_embedding` processor owns vectors and needs a deployed model ID.
`RAG_OPENSEARCH_VECTOR_FIELD`	`.env` / Compose `env_file`	`embedding_vector`	Reserved OpenSearch `knn_vector` field used by pipeline hybrid search; must not collide with OKF chunk metadata fields.
`RAG_OPENSEARCH_INGEST_MODEL_ID`	`.env` / Compose `env_file`	пусто	Deployed OpenSearch ML model ID for `opensearch-ingest-embedding`; keep empty for external embedding mode.
`RAG_OPENSEARCH_INGEST_FIELD_MAP`	`.env` / Compose `env_file`	`{"contextualized_content":"embedding_vector"}`	JSON field map for OpenSearch `text_embedding` ingest processor.
`RAG_OPENSEARCH_SEARCH_PROCESSOR`	`.env` / Compose `env_file`	`normalization`	Search pipeline processor: `normalization` for Compose-compatible score normalization or `score-ranker` for RRF on supported OpenSearch versions.
`RAG_QDRANT_URL`	`.env` / Compose `env_file`	`http://qdrant:6333`	Qdrant endpoint checked at MCP startup. Use `http://127.0.0.1:6333` from host-side runs.
`RAG_QDRANT_API_KEY`	`.env` / Compose `env_file`	пусто	Optional Qdrant API key; keep real secrets local-only.
`RAG_QDRANT_COLLECTION`	`.env` / Compose `env_file`	`okf-concepts`	Target Qdrant collection name for vector retrieval. Refresh recreates this collection only in `local`/`quality` profiles unless unsafe opt-in is set.
`RAG_SPARSE_MODEL`	`.env` / Compose `env_file`	`deterministic-sparse-v1`	Deterministic sparse vector provider for `qdrant-hybrid`; unknown sparse models fail clearly until production providers are implemented.
`RAG_SPARSE_DIMENSIONS`	`.env` / Compose `env_file`	`4096`	Sparse hashing vector dimension for deterministic sparse retrieval.
`RAG_QDRANT_HYBRID_FUSION`	`.env` / Compose `env_file`	`rrf`	Qdrant fusion method for prefetch hybrid queries: `rrf` or `dbsf`. `dbsf` requires a Qdrant version with DBSF support.
`RAG_QDRANT_PREFETCH_MULTIPLIER`	`.env` / Compose `env_file`	`3`	Multiplier for dense and sparse prefetch branch limits before Qdrant fusion.
`RAG_QDRANT_ALLOW_UNSAFE_RECREATE`	`.env` / Compose `env_file`	`false`	Explicit production opt-in for destructive Qdrant collection recreate. Keep `false` until versioned collection + alias/swap refresh is implemented.
`RAG_OPENSEARCH_ALLOW_UNSAFE_RECREATE`	`.env` / Compose `env_file`	`false`	Explicit production opt-in for destructive OpenSearch index recreate. Keep `false` until alias/swap refresh is implemented.
`RAG_OPENSEARCH_ALLOW_INSECURE_PRODUCTION`	`.env` / Compose `env_file`	`false`	Test-only escape hatch for plaintext/unauthenticated production OpenSearch endpoints. Production should use HTTPS plus auth and credential env vars, not URL userinfo/query strings.
`OPENAI_API_KEY`	`.env` / Compose `env_file`	пусто	Зарезервированный секрет для будущей generative RAG-интеграции. Не коммитьте реальное значение.
`RAG_ALLOW_DETERMINISTIC_EMBEDDINGS`	`.env` / Compose `env_file`	`false`	Test-only escape hatch: permits deterministic dense embeddings in production Qdrant modes. Keep `false` for real production.
`RAG_EMBEDDING_MODEL`	`.env` / Compose `env_file`	`deterministic-hash-v1`	Локальная deterministic embedding-модель для dev/tests и indexed retrieval smoke tests. Unknown model names fail explicitly until a real dense provider is wired.
`RAG_EMBEDDING_DIMENSIONS`	`.env` / Compose `env_file`	`64`	Размерность deterministic embedding-векторов по умолчанию.
`RAG_GENERATION_MODEL`	`.env` / Compose `env_file`	пусто	Зарезервировано: модель генерации ответов для будущей generative RAG-интеграции.
`RAG_REPHRASER_MODEL`	`.env` / Compose `env_file`	пусто	Зарезервировано: модель переформулирования запросов для будущей generative RAG-интеграции.

OKF/7D contract кратко

Каждый OKF-концепт обязан иметь frontmatter type и status. Разрешённые статусы: draft, to-review, not-valid, valid, rejected, accepted. Статус описывает состояние документа/артефакта, а не прогресс реализации; переходы между статусами рекомендательные и не являются validation gate.

7D-стадия всегда выводится из type через registry в SPEC.md. Нельзя добавлять 7D-specific frontmatter вроде stage или raci. Любой unmapped type — ошибка валидации, а отсутствие required lifecycle artifacts — отдельный coverage gap в 7D-отчётах.

HLD-схема сервиса

Simple OKF — это локальный сервис для ведения agent-readable knowledge base. На HLD-уровне у него одна граница системы: сервис принимает запросы, работает с OKF-бандлом как с источником истины и создаёт производные артефакты для навигации, поиска и отчётности.

flowchart TB
    clients["Агенты и разработчики"]

    service["Simple OKF service\nлокальный MCP/CLI сервис\n\nОсновные функции:\nOKF management\nQuality automation\nLocal RAG\n7D reporting"]

    bundle["OKF-бандл\nканоничные Markdown-концепты"]
    artifacts["Производные артефакты\nиндексы, граф, dashboard, RAG-индекс"]
    external["Будущие внешние RAG-интеграции"]

    clients -->|"запросы"| service
    service -->|"читает и изменяет"| bundle
    service -->|"создаёт и обновляет"| artifacts
    service -. "опционально в будущем" .-> external

На схеме:

Агенты и разработчики — потребители сервиса через MCP API или CLI.
Simple OKF service — единственная запускаемая система; внутри неё находятся OKF tooling, Local RAG и 7D-отчётность.
OKF-бандл — источник истины; знания хранятся как Markdown-концепты.
Производные артефакты — пересобираемые файлы для индексов, графа, dashboard и локального RAG.
Будущие внешние RAG-интеграции — не входят в текущий локальный запуск.

Полезные команды

Через make:

PY='uv run python' make validate       # проверить Python-модули и OKF-бандл
PY='uv run python' make indexes        # пересобрать okf/**/index.md
PY='uv run python' make graph          # собрать artifacts/okf/graph.json и graph.html
PY='uv run python' make rag-check      # проверить и обновить локальный RAG-индекс
PY='uv run python' make 7d-report      # вывести компактный отчет по 7D-стадиям
PY='uv run python' make 7d-dashboard   # собрать artifacts/7d-dashboard.html
PY='uv run python' make e2e            # deterministic local E2E-проверки

Без make:

uv run python -m okf_mcp validate okf
uv run python -m okf_mcp indexes okf
uv run python -m okf_mcp graph okf --out artifacts/okf/graph.json --html-out artifacts/okf/graph.html
uv run python -m okf_mcp rag refresh --env .env --pretty
uv run python -m okf_mcp rag retrieve "okf" --env .env --answer --limit 3 --pretty
uv run python -m okf_mcp 7d validate --bundle okf

Документация

Для пользователей:

быстрый запуск и частые команды — этот README.md;
основной OKF-бандл: okf/;
production-like RAG/MCP runbook: docs/operations/rag_production_hardening.md.

Для технических специалистов:

архитектура и extension points: docs/technical-overview.md;
правила контрибуции: CONTRIBUTING.md;
canonical project contract: SPEC.md;
правила для агентов: AGENTS.md;
MCP/CLI implementation: okf_mcp/.

Если что, пишите issues и предлагайте PR.

Коля

Name		Name	Last commit message	Last commit date
Latest commit History 33 Commits
.agents/skills		.agents/skills
docs		docs
frontend		frontend
okf		okf
okf_mcp		okf_mcp
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.mcp.json		.mcp.json
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SPEC.md		SPEC.md
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

Simple OKF Template

Что это

Локальный запуск

Требования

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

Что делать дальше

RAG: поиск и ответы

Запуск MCP-сервера

Запуск через Docker Compose

Переменные окружения

OKF/7D contract кратко

HLD-схема сервиса

Полезные команды

Документация

About

Uh oh!

Releases

Contributors

Uh oh!

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Simple OKF Template

Что это

Локальный запуск

Требования

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

Что делать дальше

RAG: поиск и ответы

Запуск MCP-сервера

Запуск через Docker Compose

Переменные окружения

OKF/7D contract кратко

HLD-схема сервиса

Полезные команды

Документация

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Contributors

Uh oh!

Languages