Metadata-Version: 2.4
Name: simbrain
Version: 0.1.1
Summary: SimBrain document ingestion and retrieval CLI for a knowledge base
Requires-Python: >=3.12
Requires-Dist: elasticsearch[async]>=8.0.0
Requires-Dist: fastmcp<4.0.0,>=3.0.0
Requires-Dist: filelock>=3.16.0
Requires-Dist: mineru-open-sdk>=0.2.5
Requires-Dist: openai>=1.0.0
Requires-Dist: openpyxl>=3.0.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pypdf>=4.0.0
Requires-Dist: python-docx>=1.0.0
Requires-Dist: python-dotenv>=1.2.2
Description-Content-Type: text/markdown

# SimBrain

[简体中文](README_zh-CN.md) | English

SimBrain incrementally ingests local documents into Elasticsearch and provides MCP tools and CLIs for ingestion, project inspection, progress monitoring, and retrieval.

## Quick start

SimBrain defaults to local Ollama at `http://localhost:11434` with the `bge-m3` model. Start Ollama and install the model first:

```bash
ollama pull bge-m3
```

Every usage mode requires Elasticsearch. At minimum, configure its endpoint and authentication:

```dotenv
ES_URL=https://your-es-host:9200
ES_API_KEY=your_es_api_key
```

See [.env.example](.env.example) for all fields and defaults. When running from source, copy it to `.env`:

```bash
cp .env.example .env
```

`MINERU_API_TOKEN` is optional. When configured, MinerU is preferred for PDF parsing; otherwise SimBrain falls back to pypdf.

Supported document formats: PDF, DOCX, TXT, TEXT, Markdown, CSV, and XLSX.

## Use with MCP

SimBrain exposes an MCP server over standard input/output (stdio). Once published on PyPI, start it with:

```bash
uvx --from simbrain simbrain-mcp
```

The server exposes these tools:

| Tool | Arguments | Purpose |
| --- | --- | --- |
| `simbrain-ingest` | `input_dir`, `output_dir`, `project` | Incremental ingestion |
| `simbrain-status` | `output_dir` | List all projects |
| `simbrain-status-realtime` | `output_dir`, `project` | Monitor ingestion progress |
| `simbrain-search` | `question`, `project`, `top_k` | Hybrid vector and keyword retrieval |

### Codex configuration

Add this to `~/.codex/config.toml`:

```toml
[mcp_servers.simbrain]
command = "uvx"
args = ["--from", "simbrain", "simbrain-mcp"]

[mcp_servers.simbrain.env]
ES_URL = "https://your-es-host:9200"
ES_API_KEY = "your_es_api_key"
MINERU_API_TOKEN = "your_mineru_token"
```

Or register it from the command line:

```bash
codex mcp add simbrain \
  --env ES_URL=https://your-es-host:9200 \
  --env ES_API_KEY=your_es_api_key \
  --env MINERU_API_TOKEN=your_mineru_token \
  -- uvx --from simbrain simbrain-mcp
```

### Claude Desktop configuration

Add this entry under `mcpServers` in `claude_desktop_config.json`:

```json
{
  "simbrain": {
    "command": "uvx",
    "args": ["--from", "simbrain", "simbrain-mcp"],
    "env": {
      "ES_URL": "https://your-es-host:9200",
      "ES_API_KEY": "your_es_api_key",
      "MINERU_API_TOKEN": "your_mineru_token"
    }
  }
}
```

Remove `MINERU_API_TOKEN` if MinerU is not needed. All remaining settings use the defaults from [.env.example](.env.example). To use an OpenAI-compatible embedding service, set `EMBEDDING_PROVIDER`, `EMBEDDING_URL`, `EMBEDDING_API_KEY`, and `EMBEDDING_MODEL` together.

## Use with the CLI

The examples below use the PyPI package. When developing this repository, replace `uvx --from simbrain` with `uv run`.

### Incremental ingestion

```bash
uvx --from simbrain simbrain-ingest \
  --input-dir ./docs \
  --output-dir ./output \
  --project my-knowledge-base
```

Files with the same name are updated, unchanged files are skipped, and historical files omitted from the current input are retained.

### List all projects

```bash
uvx --from simbrain simbrain-status --output-dir ./output
```

### Monitor ingestion progress

```bash
uvx --from simbrain simbrain-status \
  --output-dir ./output \
  --project my-knowledge-base
```

### Search a project

```bash
uvx --from simbrain simbrain-search \
  --question "How do I configure access permissions?" \
  --project my-knowledge-base \
  --top-k 10
```

`top-k` must be between 1 and 100. Results contain source chunks and metadata; SimBrain does not generate an LLM answer.

## Output and tests

Successful CLI calls return JSON. The progress command emits JSON Lines when its state changes.

Run tests:

```bash
uv run pytest -q
```

To include the Elasticsearch integration test:

```bash
SIMBRAIN_TEST_ES_URL=http://localhost:9200 uv run pytest -q -m integration
```
