own-rag-cli 0.0.1-snapshot → 0.0.3-snapshot

package/README.md

@@ -1,133 +1,220 @@
-# MCP binary checksum (SHA-256, payload without shebang): `3246eeb57f901742d915e0bce37fa96f059e149a57bbce73095ff4e5ea51d8d4`
-
 # own-rag
 
-Local RAG for codebases with:
-- ChromaDB (Docker)
-- MCP server (`mcp-rag-server`)
-- CPU embeddings (`jina`, `bge`, `hybrid`)
-- Cross-platform setup (`Linux` and `macOS`)
+Local RAG for codebases with ChromaDB + MCP, focused on simple setup and local control.
+
+Language: English (default) | Portuguese: `README.pt-br.md`
 
-## Why this repo
+## Why use own-rag
 
-`own-rag` lets you index local projects and query them from MCP-compatible tools (Claude/Cursor).
+- Search your codebase semantically from MCP clients (Claude/Cursor).
+- Keep data local by default.
+- Run on CPU (no GPU required).
+- Choose between safer memory usage (`autotune`) or higher throughput (`max-performance`).
 
-It includes:
-- installers: `rag-setup.run`, `rag-setup-macos.run`
-- MCP server source: `bin/mcp_server.py`
-- indexer source: `bin/indexer_full.py`
-- monitor and wrapper scripts
+## What gets installed
 
-## Source vs Artifact
+- ChromaDB container (Docker)
+- Python virtual environment (`~/.rag_venv`)
+- MCP server binary (`~/.local/bin/mcp-rag-server`)
+- Setup runners (`rag-setup.run`, `rag-setup-macos.run`)
+- CLI wrapper command: `rag`
 
-This repo is fully auditable:
-- source of logic: `bin/*.py` and `bin/*.sh`
-- generated artifacts: `rag-setup.run`, `rag-setup-macos.run`
+## Install and run
 
-To refresh embedded payloads from source files:
+### Option A: npm (recommended)
 
 ```bash
-./bin/build_run.sh
-./bin/build_run_macos.sh
+npm install -g own-rag-cli
+rag run /path/to/your/project
 ```
 
-## Quick Start
+If you run `rag run` without a path, it asks whether to use the current directory.
 
-### Linux
+### Option B: direct `.run`
+
+Linux:
 
 ```bash
 chmod +x rag-setup.run
-./rag-setup.run /path/to/project
+./rag-setup.run /path/to/your/project
 ```
 
-### macOS
+macOS:
 
 ```bash
 chmod +x rag-setup-macos.run
-./rag-setup-macos.run /path/to/project
+./rag-setup-macos.run /path/to/your/project
 ```
 
-### NPM wrapper
+## Main commands
 
 ```bash
-rag run /path/to/project
-rag monitor
-rag remove
+rag run /path/to/project        # full setup + indexing
+rag monitor                     # interactive Chroma monitor
+rag monitor full                # full monitor dashboard
+rag remove                      # full local uninstall (double confirmation)
+rag remove --force              # uninstall without confirmation prompts
 ```
 
-## What setup does
+## Configuration files and paths
 
-1. Creates `~/.rag_venv` and installs dependencies.
-2. Starts ChromaDB in Docker with persistent volume (`~/.rag_db`).
-3. Installs `mcp-rag-server` in `~/.local/bin`.
-4. Optionally updates MCP config files (`.claude.json`, Cursor config).
-5. Indexes the project.
+### 1) Runtime config (CLI-level)
 
-## ChromaDB Port Behavior
+Path: `~/.own-rag-cli.json`
 
-- Default host port is `8000`.
-- During ChromaDB install/reinstall, setup asks for the port.
-- The installer checks if the chosen port is already in use using native tools:
-  - Linux: `ss` (fallback: `lsof` / `netstat`)
-  - macOS: `lsof` (fallback: `netstat`)
-- If the port is busy, it asks for another one.
-- In non-interactive runs, it auto-selects the next free port.
-- Selected port is propagated to:
-  - Docker Compose mapping
-  - health checks
-  - MCP config (`CHROMA_PORT`)
-  - indexer runtime (`MCP_CHROMA_PORT`)
+Purpose:
+- Stores Chroma endpoint (`scheme`, `host`, `port`).
+- Stores latest indexing batch fields (`indexing.embedding_batch_size`, `indexing.batch_count`).
 
-## Performance Profiles
+Example:
 
-Available in indexer/setup:
-- `autotune` (recommended): uses local machine metrics and short benchmark.
-- `max-performance`: higher throughput and higher memory usage risk.
+```json
+{
+  "chroma": {
+    "scheme": "http",
+    "host": "localhost",
+    "port": 8000
+  },
+  "indexing": {
+    "embedding_batch_size": 4,
+    "batch_count": 4
+  }
+}
+```
 
-`max-performance` warning shown by setup:
+### 2) Indexer tuning config
 
-```text
-Este modo pode elevar consideravelmente o consumo de memória e causar encerramento por OOM (exit 137).
-```
+Path: `~/.cache/own-rag-cli/indexer_tuning.json`
 
-## Key Environment Variables
+Purpose:
+- Persists model/profile/tuning decisions (`chunk_size`, `chunk_overlap`, `embedding_batch_size`, etc.).
+- Loaded by both indexer and MCP server to keep behavior consistent across re-runs.
 
-- `MCP_EMBEDDING_MODEL=jina|bge|hybrid`
-- `MCP_JINA_QUANTIZATION=default|dynamic-int8`
-- `MCP_PERF_PROFILE=autotune|max-performance`
-- `MCP_CHROMA_PORT=8000`
-- `MCP_CHUNK_SIZE`
-- `MCP_CHUNK_OVERLAP`
-- `MCP_EMBEDDING_BATCH_SIZE`
+### 3) Database and runtime directories
+
+- Chroma data: `~/.rag_db`
+- Python venv: `~/.rag_venv`
+- Installed binaries/scripts: `~/.local/bin/`
+
+### 4) MCP client config files (optional auto-update)
+
+- Claude Code: `~/.claude.json`
+- Cursor: `~/.cursor/mcp.json`
+- Cursor (alt, Linux/macOS variants): `~/.config/Cursor/User/mcp.json` or `~/Library/Application Support/Cursor/User/mcp.json`
+
+## Choosing the embedding model (practical guidance)
 
-## Useful Commands
+These are practical memory guidelines for CPU usage. Real usage depends on project size, file size, and other running processes.
+
+| Choice | Use case | Approx RAM target |
+|---|---|---|
+| `bge` (`BAAI/bge-m3`) | mixed docs + code, safer memory | 8-16 GiB |
+| `jina` (`jinaai/jina-embeddings-v3`, default) | code-focused quality | 32-64 GiB (48+ GiB preferred) |
+| `hybrid` (`jina v2 + bge`) | two collections, broader retrieval strategy | 24-48 GiB |
+
+Notes:
+- Jina on CPU is heavy; with low free RAM/swap, you can see slowdowns or OOM (`exit 137`).
+- If your machine has limited memory, start with `bge`.
+
+## Performance profile
+
+During setup/indexing, choose one profile:
+
+- `autotune` (recommended):
+  - Runs a short local benchmark (`model.encode`) with `psutil` metrics.
+  - Tries to keep memory in a safer range (roughly cost-benefit target).
+  - Automatically adjusts `MCP_EMBEDDING_BATCH_SIZE`, `MCP_CHUNK_SIZE`, `MCP_CHUNK_OVERLAP`.
+
+- `max-performance`:
+  - Uses more aggressive throughput-oriented parameters.
+  - Explicit warning is shown because memory can increase considerably.
+
+## Chroma endpoint behavior
+
+- Default local endpoint is `http://localhost:8000`.
+- Setup checks if the selected port is already in use.
+- If `host` in `~/.own-rag-cli.json` is remote (not localhost/127.0.0.1/::1), local Docker startup is skipped.
+
+## Common flows
+
+### Reindex only
 
 ```bash
-# only index (infra already installed)
 ./rag-setup.run /path/to/project --only-index
+```
+
+### Skip index step
 
-# skip indexing
+```bash
 ./rag-setup.run /path/to/project --skip-index
+```
 
-# force reinstall
-./rag-setup.run /path/to/project --reinstall
+### Change model later
 
-# force model change flow
+```bash
 ./rag-setup.run --change-model /path/to/project
 ```
 
-## Development
+This flow warns about resetting Chroma collections and requiring full reindex.
+
+## Environment overrides
+
+Main overrides:
+
+- `MCP_EMBEDDING_MODEL=jina|bge|hybrid`
+- `MCP_JINA_QUANTIZATION=default|dynamic-int8`
+- `MCP_PERF_PROFILE=autotune|max-performance`
+- `MCP_EMBEDDING_BATCH_SIZE=<int>`
+- `MCP_CHUNK_SIZE=<int>`
+- `MCP_CHUNK_OVERLAP=<int>`
+- `OWN_RAG_CLI_CONFIG_FILE=<path>`
+- `MCP_INDEXER_CONFIG_FILE=<path>`
+- `MCP_CHROMA_SCHEME=http|https`
+- `MCP_CHROMA_HOST=<host>`
+- `MCP_CHROMA_PORT=<port>`
+
+## Checksum verification (`.run`)
+
+Current checksum (documented in this repo) refers to payload hash.
+
+Manual verification (Linux/macOS):
+
+```bash
+sha256sum rag-setup.run
+sha256sum rag-setup-macos.run
+```
+
+On macOS without `sha256sum`:
+
+```bash
+shasum -a 256 rag-setup.run
+shasum -a 256 rag-setup-macos.run
+```
+
+## Source transparency
+
+Project logic is in source files (`bin/*.py`, `bin/*.sh`).
+Generated artifacts:
+
+- `rag-setup.run`
+- `rag-setup-macos.run`
+
+Rebuild artifacts after source changes:
+
+```bash
+./bin/build_run.sh
+./bin/build_run_macos.sh
+```
 
-- Edit source files in `bin/`.
-- Rebuild payloads with `./bin/build_run.sh` and `./bin/build_run_macos.sh`.
-- Validate before commit:
+## Validation before release
 
 ```bash
 bash -n rag-setup.run
 bash -n rag-setup-macos.run
-python3 -m py_compile bin/indexer_full.py
+python3 -m py_compile bin/indexer_full.py bin/mcp_server.py
+npm pack --dry-run
 ```
 
 ## License
 
-MIT (or your preferred OSS license file in this repo).
+MIT

package/README.pt-br.md

@@ -0,0 +1,218 @@
+# own-rag
+
+RAG local para codebases com ChromaDB + MCP, focado em instalação simples e controle local.
+
+Idioma: Português (PT-BR) | English: `README.md`
+
+## Por que usar o own-rag
+
+- Busca semântica no seu código via clientes MCP (Claude/Cursor).
+- Dados locais por padrão.
+- Execução em CPU (sem GPU obrigatória).
+- Escolha entre perfil mais seguro de memória (`autotune`) ou maior throughput (`max-performance`).
+
+## O que é instalado
+
+- Container ChromaDB (Docker)
+- Ambiente virtual Python (`~/.rag_venv`)
+- Binário MCP (`~/.local/bin/mcp-rag-server`)
+- Instaladores (`rag-setup.run`, `rag-setup-macos.run`)
+- Comando wrapper: `rag`
+
+## Instalação e execução
+
+### Opção A: npm (recomendado)
+
+```bash
+npm install -g own-rag-cli
+rag run /caminho/do/projeto
+```
+
+Se executar `rag run` sem caminho, o CLI pergunta se deve usar o diretório atual.
+
+### Opção B: `.run` direto
+
+Linux:
+
+```bash
+chmod +x rag-setup.run
+./rag-setup.run /caminho/do/projeto
+```
+
+macOS:
+
+```bash
+chmod +x rag-setup-macos.run
+./rag-setup-macos.run /caminho/do/projeto
+```
+
+## Comandos principais
+
+```bash
+rag run /caminho/do/projeto    # setup completo + indexação
+rag monitor                    # monitor interativo do Chroma
+rag monitor full               # painel completo do monitor
+rag remove                     # desinstalação completa local (dupla confirmação)
+rag remove --force             # desinstala sem prompts de confirmação
+```
+
+## Arquivos e caminhos de configuração
+
+### 1) Configuração de runtime (nível CLI)
+
+Caminho: `~/.own-rag-cli.json`
+
+Finalidade:
+- Armazena endpoint do Chroma (`scheme`, `host`, `port`).
+- Armazena campos de batch da indexação (`indexing.embedding_batch_size`, `indexing.batch_count`).
+
+Exemplo:
+
+```json
+{
+  "chroma": {
+    "scheme": "http",
+    "host": "localhost",
+    "port": 8000
+  },
+  "indexing": {
+    "embedding_batch_size": 4,
+    "batch_count": 4
+  }
+}
+```
+
+### 2) Configuração de tuning do indexador
+
+Caminho: `~/.cache/own-rag-cli/indexer_tuning.json`
+
+Finalidade:
+- Persiste decisões de modelo/perfil/tuning (`chunk_size`, `chunk_overlap`, `embedding_batch_size`, etc.).
+- É lido por indexador e MCP server para manter consistência entre execuções.
+
+### 3) Diretórios de dados e runtime
+
+- Dados do Chroma: `~/.rag_db`
+- Venv Python: `~/.rag_venv`
+- Binários/scripts instalados: `~/.local/bin/`
+
+### 4) Arquivos de configuração MCP (auto-update opcional)
+
+- Claude Code: `~/.claude.json`
+- Cursor: `~/.cursor/mcp.json`
+- Cursor (variações Linux/macOS): `~/.config/Cursor/User/mcp.json` ou `~/Library/Application Support/Cursor/User/mcp.json`
+
+## Escolha do modelo de embeddings (guia prático)
+
+Valores abaixo são referência prática para CPU. O consumo real depende do tamanho do projeto, arquivos e processos concorrentes.
+
+| Opção | Quando usar | RAM desejada (aprox.) |
+|---|---|---|
+| `bge` (`BAAI/bge-m3`) | docs + código, menor risco de memória | 8-16 GiB |
+| `jina` (`jinaai/jina-embeddings-v3`, padrão) | foco em qualidade para código | 32-64 GiB (ideal 48+ GiB) |
+| `hybrid` (`jina v2 + bge`) | duas coleções, recuperação mais ampla | 24-48 GiB |
+
+Notas:
+- Jina em CPU é pesado; com pouca RAM/swap livre pode ocorrer lentidão ou OOM (`exit 137`).
+- Se a máquina for limitada, comece com `bge`.
+
+## Perfil de performance
+
+Durante setup/indexação, escolha:
+
+- `autotune` (recomendado):
+  - Executa micro-benchmark local (`model.encode`) com métricas `psutil`.
+  - Busca faixa mais estável de memória (custo-benefício).
+  - Ajusta automaticamente `MCP_EMBEDDING_BATCH_SIZE`, `MCP_CHUNK_SIZE`, `MCP_CHUNK_OVERLAP`.
+
+- `max-performance`:
+  - Usa parâmetros mais agressivos para throughput.
+  - Exibe aviso explícito de maior consumo de memória.
+
+## Comportamento do endpoint Chroma
+
+- Endpoint local padrão: `http://localhost:8000`.
+- O setup verifica se a porta escolhida já está em uso.
+- Se `host` em `~/.own-rag-cli.json` for remoto (não localhost/127.0.0.1/::1), o setup não sobe Docker local.
+
+## Fluxos comuns
+
+### Reindexar somente
+
+```bash
+./rag-setup.run /caminho/do/projeto --only-index
+```
+
+### Pular indexação
+
+```bash
+./rag-setup.run /caminho/do/projeto --skip-index
+```
+
+### Trocar modelo depois
+
+```bash
+./rag-setup.run --change-model /caminho/do/projeto
+```
+
+Esse fluxo alerta sobre reset das coleções Chroma e reindexação completa.
+
+## Variáveis de ambiente (override)
+
+Principais variáveis:
+
+- `MCP_EMBEDDING_MODEL=jina|bge|hybrid`
+- `MCP_JINA_QUANTIZATION=default|dynamic-int8`
+- `MCP_PERF_PROFILE=autotune|max-performance`
+- `MCP_EMBEDDING_BATCH_SIZE=<int>`
+- `MCP_CHUNK_SIZE=<int>`
+- `MCP_CHUNK_OVERLAP=<int>`
+- `OWN_RAG_CLI_CONFIG_FILE=<path>`
+- `MCP_INDEXER_CONFIG_FILE=<path>`
+- `MCP_CHROMA_SCHEME=http|https`
+- `MCP_CHROMA_HOST=<host>`
+- `MCP_CHROMA_PORT=<port>`
+
+## Verificação de checksum (`.run`)
+
+Verificação manual (Linux/macOS):
+
+```bash
+sha256sum rag-setup.run
+sha256sum rag-setup-macos.run
+```
+
+No macOS sem `sha256sum`:
+
+```bash
+shasum -a 256 rag-setup.run
+shasum -a 256 rag-setup-macos.run
+```
+
+## Transparência de código
+
+Lógica principal em arquivos-fonte (`bin/*.py`, `bin/*.sh`).
+Artefatos gerados:
+
+- `rag-setup.run`
+- `rag-setup-macos.run`
+
+Para regenerar artefatos após mudanças no fonte:
+
+```bash
+./bin/build_run.sh
+./bin/build_run_macos.sh
+```
+
+## Validação antes de publicar
+
+```bash
+bash -n rag-setup.run
+bash -n rag-setup-macos.run
+python3 -m py_compile bin/indexer_full.py bin/mcp_server.py
+npm pack --dry-run
+```
+
+## Licença
+
+MIT