README.md

---
license: apache-2.0
tags:
  - sentence-transformers
  - feature-extraction
  - intent-classification
  - retrieval
  - routing
  - agent-runtime
  - mind-nerve
language:
  - en
base_model: BAAI/bge-small-en-v1.5
pipeline_tag: sentence-similarity
library_name: sentence-transformers
---

# mind-nerve — Phase 1 (v1.1-oss)

**Intent-classification preselector for agent runtimes.**

A small, fast classifier that sits between a user request and the host runtime. It reads the request, decides which subset of available tools/skills/agents is relevant, and hands the host a short list — so the downstream LLM never sees the full library in its system prompt.

Result: library size decouples from token cost. Hosting 4,400 skills costs the same prompt budget as hosting 44, because only the top-K are ever loaded per turn.

## Usage

```bash
pip install mind-nerve
```

```python
from mind_nerve import route
result = route("git status", top_k=5)
for r in result.routes:
    print(r.score, r.name, r.kind)
```

The first call auto-downloads this checkpoint into
`~/.local/share/mind-nerve/runtime/`. To pre-seed or use a custom location,
set `MIND_NERVE_RUNTIME_DIR=/path/to/your/runtime/`.

## Model

- **Base model**: `BAAI/bge-small-en-v1.5` (fine-tuned)
- **Loss**: MultipleNegativesRankingLoss
- **Training**: 3 epochs, batch 32, lr 2e-5, max_len 256, seed 1337
- **Hardware**: single CUDA GPU, 119.5 s wall-clock
- **Training date**: 2026-05-16T04:00:53Z

## Catalog

- **Version**: `v1.1-oss` (public-clean — no STARGA-private content in the training corpus)
- **Candidate pool**: 11,922 routing candidates (skills + tools + agents)
- **Corpus hash**: `1cd130fa98255241b93aaa2fe6a8086bcbf6fc0627c904008cf48ba9f233536d`
- **Tokenizer hash**: `cc2a5502d0fa683c98d59da77af1e4ef3a3812e7e2f345c1d8d7a90bed99d817`
- **Model hash**: `83d4d390469bc1bc6a6cac3b9ab8448dcfcd9ac2ba1ab9fce9348c64012681a6`

## Metrics (held-out eval, 1,193 pairs)

|         | Baseline (BGE off-the-shelf) | After Phase 1 fine-tune | Δ      |
| ------- | ---------------------------- | ----------------------- | ------ |
| Top-1   | 0.7527                       | **0.8449**              | +0.092 |
| Top-5   | 0.9296                       | **0.9606**              | +0.031 |
| Top-10  | 0.9489                       | **0.9707**              | +0.022 |

## What's in this repo

- `checkpoint/` — sentence-transformers checkpoint (model.safetensors + tokenizer + config)
- `manifest.json` — full provenance (corpus_hash, model_hash, training config, metrics)
- `route_table.npy` — precomputed catalog embeddings (11,922 × 384, float32)
- `route_table.jsonl` — catalog metadata (one JSON object per row of `route_table.npy`)

## Status

**Phase 1, public alpha.** Inference runs on PyTorch via the fine-tuned BGE encoder. Phase 2 (target Q3 2027) replaces the PyTorch path with a native MIND Q16.16 inference loop and adds:

- Cross-architecture bit-identity gate (x86 CPU vs CUDA)
- p95 ≤ 30 ms latency budget on 4-core CPU

Phase 2 is gated on `mindc` 0.2.6 (`pub fn` → C symbol export) and 0.3.0 (cdylib emit).

## License

This model card and the weights it points at are released under **Apache-2.0**.

The PyPI wheel `mind-nerve` bundles a FORTRESS-protected `libmindnerve.so` whose source remains private (STARGA Commercial). The wheel is Apache-2.0; the bundled binary is the protected runtime layer that activates in Phase 2. The Phase 1 inference path published here does not depend on the protected binary.

For commercial deployments needing per-customer FORTRESS-locked builds of the runtime layer, contact `license@star.ga`.

## Citation

```
@software{mind_nerve_2026,
  author  = {STARGA, Inc.},
  title   = {mind-nerve: Intent-classification preselector for agent runtimes},
  year    = {2026},
  url     = {https://github.com/star-ga/mind-nerve},
  version = {0.1.0-alpha.3},
}
```