python -m pip install --upgrade pip

pip install -e .[dev,test]

- name: Dependency audit (pip-audit)

run: |

python -m pip install pip-audit

pip-audit

- name: Ruff (lint + format check)

run: ruff check .

- **Stigmergic pheromones** reward useful documents but decay over time, preventing filter bubbles.

- **MMR + ε-greedy** introduces diversity without tanking relevance.

- **Zero external dependencies by default.** Uses a hashing trick for embeddings so you can see results instantly, but slots in any vector model when you’re ready.

- **Adapters included.** LangChain and LlamaIndex adapters ship in `neuralcache.adapters` and only import their extras when you use them.

- **Adapters included.** LangChain and LlamaIndex adapters ship in `neuralcache.adapters`; install them on demand with `pip install "neuralcache[adapters]"`.

- **CLI + REST API + FastAPI docs** give you multiple ways to integrate and debug.

- **Plus API** adds `/rerank/batch` and Prometheus-ready `/metrics` endpoints when you run `uvicorn neuralcache.api.server_plus:app` (install the `neuralcache[ops]` extra for dependencies).

- **SQLite persistence out of the box.** `neuralcache.storage.sqlite_state.SQLiteState` keeps narrative + pheromone state durable across workers without JSON file juggling.

- **REST API** (`uvicorn neuralcache.api.server:app`) with `/rerank`, `/feedback`, `/metrics`, and `/healthz` endpoints.

- **Plus API** (`uvicorn neuralcache.api.server_plus:app`) adds `/rerank/batch`, Prometheus `/metrics`, and mounts the legacy routes under `/v1`.

- **CLI** (`neuralcache "<query>" docs.jsonl --top-k 5`) for quick experiments and scripting.

- **LangChain adapter**: `from neuralcache.adapters import NeuralCacheLangChainReranker`

- **LlamaIndex adapter**: `from neuralcache.adapters import NeuralCacheLlamaIndexReranker`

- **LangChain adapter** (`pip install "neuralcache[adapters]"`): `from neuralcache.adapters import NeuralCacheLangChainReranker`

- **LlamaIndex adapter** (`pip install "neuralcache[adapters]"`): `from neuralcache.adapters import NeuralCacheLlamaIndexReranker`

See [`examples/quickstart.py`](examples/quickstart.py) for an end-to-end script.

---

## Feedback API: closing the loop

Send successful reranks back to NeuralCache so the narrative EMA and pheromone

signals keep learning:

```http

POST /feedback

Content-Type: application/json

{

"query": "How do I rotate API keys?",

"selected_ids": ["doc-42", "doc-71"],

"success": 0.9,

"best_doc_text": "Rotate keys via the dashboard > API tokens",

"best_doc_embedding": [0.01, 0.32, -0.55, ...]

}

```

- `selected_ids` **must** match the `id` values returned by `/rerank`. The API

rejects unknown IDs to prevent stale writes.

- `success` scores the overall outcome (`1.0` for complete resolution, `0.0`

for failure). Values below `settings.narrative_success_gate` are ignored for

narrative updates but still count toward pheromone decay.

- `best_doc_text`/`best_doc_embedding` are optional hints that let the reranker

update the narrative vector even when a caller reformats the answer before

returning it to the user.

On success the endpoint responds with `{"status": "ok"}`.

Tip: throttle feedback submissions with a short debounce window (e.g., only send

feedback after end-users click “helpful”) to avoid promoting documents for noisy

sessions.

---

## Privacy & retention tips

- Set `NEURALCACHE_STORAGE_PERSISTENCE_ENABLED=false` to run fully in-memory. Narrative

vectors and pheromones reset on process restart and never touch disk.

- Configure `NEURALCACHE_STORAGE_RETENTION_DAYS` (e.g., `7`) to purge pheromones and

narrative state older than the retention window on startup. SQLite purges directly

via `metadata`/`pheromones`, and the JSON fallback trims files in place.

- Rotate SQLite files regularly or place them on encrypted storage. Review

[`SECURITY.md`](SECURITY.md) for reporting procedures and deployment guardrails.

These controls let you scope how long user-derived signals persist while still

benefiting from adaptive reranking.

---

## Configuration essentials

| Env var | Purpose | Default |

| `NEURALCACHE_MAX_DOCUMENTS` | Safety cap on rerank set size | `128` |

| `NEURALCACHE_MAX_TEXT_LENGTH` | Hard limit on document length (characters) | `8192` |

| `NEURALCACHE_STORAGE_DIR` | Where SQLite + JSON state is stored | `storage/` |

| `NEURALCACHE_STORAGE_PERSISTENCE_ENABLED` | Disable to keep narrative + pheromones in-memory only | `true` |

| `NEURALCACHE_STORAGE_RETENTION_DAYS` | Days before old state is purged on boot (supports SQLite + JSON) | _unset_ |

| `NEURALCACHE_GATING_MODE` | Cognitive gate mode (`off`, `auto`, `on`) | `auto` |

| `NEURALCACHE_GATING_THRESHOLD` | Uncertainty threshold for trimming | `0.45` |

| `NEURALCACHE_GATING_MIN_CANDIDATES` | Lower bound for rerank candidates | `8` |

Adjust everything via `.env`, environment variables, or direct `Settings(...)` instantiation.

Persistence happens automatically using SQLite (or JSON fallback) so narrative and pheromone stores survive restarts. Point `NEURALCACHE_STORAGE_DIR` at shared storage for multi-worker deployments, or import `SQLiteState` directly if you need to wire the persistence layer into an existing app container.

Persistence happens automatically using SQLite (or JSON fallback) so narrative and pheromone stores survive restarts. Point `NEURALCACHE_STORAGE_DIR` at shared storage for multi-worker deployments, or import `SQLiteState` directly if you need to wire the persistence layer into an existing app container. Under the hood the SQLite state:

- enables **WAL mode** with `synchronous=NORMAL` so multiple workers can read while a writer appends.

- tracks a `metadata` row with the current schema version (`SQLiteState.schema_version()`), raising if a newer schema is encountered so upgrades can run explicit migrations before boot.

- stores pheromone exposures and timestamps so retention/evaporation policies can prune long-lived records.

---

# Security Policy

## Supported Versions

We support the most recent minor release line of `neuralcache`. Security fixes are

backported to the latest published version on PyPI. Older minors may receive fixes

on a best-effort basis only if they are no more than one release behind.

| Version | Supported |

| ------- | --------- |

| 0.3.x | ✅ |

| < 0.3 | ⚠️ (upgrade recommended) |

## Reporting a Vulnerability

If you discover a security issue, please email **security@carnotengine.com** with the

following details:

- A clear description of the vulnerability.

- Steps or proof-of-concept required to reproduce the issue.

- The impact you believe the vulnerability has.

- Any suggested fixes or mitigations.

We aim to acknowledge new reports within **3 business days** and will keep you updated

on progress. Please do not open public GitHub issues for potential vulnerabilities.

## Handling Sensitive Data

NeuralCache can store reranking telemetry in SQLite. When deploying to production:

- Place the SQLite database on encrypted storage.

- Rotate API tokens stored in environment variables regularly.

- Run the API behind TLS (e.g., via a reverse proxy such as Nginx or Caddy).

- Set `NEURALCACHE_API_TOKENS` to enforce bearer-token authentication.

## Dependency Management

- The project uses constrained versions for FastAPI and Uvicorn to avoid known security

advisories. Update pins only after verifying advisories in the

[Python Packaging Advisory Database](https://github.com/pypa/advisory-database).

- The CI workflow runs [`pip-audit`](https://github.com/pypa/pip-audit) on every pull

request and push to `main` to detect vulnerable dependencies early.

- Use Dependabot updates to stay ahead of transitive dependency advisories.

## Secure Development Checklist

- Run `ruff`, `mypy`, and `pytest` locally before sending a pull request.

- Avoid storing secrets in the repository or sample configuration files.

- Keep container builds based on the published Dockerfile up to date with the

latest security patches from the base image.

## Coordinated Disclosure

We prefer coordinated disclosure. After we release a fix, we'll work with you

on appropriate public communication and attribution if desired. Thank you for

helping us keep NeuralCache safe for everyone.

]

dependencies = [

"fastapi>=0.110,<1.0",

"uvicorn[standard]>=0.24",

"fastapi>=0.111,<0.114",

"uvicorn[standard]>=0.24,<0.30",

"numpy>=1.26",

"pydantic>=2.6",

"pydantic-settings>=2.2",

"orjson>=3.9",

"python-dateutil>=2.9",

"rich>=13.7",

# optional adapters (safe to import conditionally)

"langchain-core>=0.2; python_version >= '3.11'",

"llama-index-core>=0.10; python_version >= '3.11'",

]

[project.optional-dependencies]

"sentence-transformers>=2.6.0"

]

ops = ["prometheus-client>=0.20", "requests>=2.32"]

adapters = [

"langchain-core>=0.2",

"llama-index-core>=0.10",

]

[project.scripts]

neuralcache = "neuralcache.cli:app"

storage_backend: str = "sqlite"

storage_dir: str = "storage"

storage_db_name: str = "neuralcache.db"

storage_persistence_enabled: bool = True

storage_retention_days: float | None = None

narrative_store_path: str = "narrative.json"

pheromone_store_path: str = "pheromones.json"

import json

import pathlib

import time

from contextlib import suppress

import numpy as np

self.path = (base_path / path).as_posix()

self._sqlite = sqlite_state

self.v = np.zeros((dim,), dtype=np.float32)

self._updated_ts = 0.0

self._load()

def _load(self) -> None:

if self.backend == "memory":

self._updated_ts = 0.0

return

if self.backend == "sqlite" and self._sqlite is not None:

with suppress(Exception):

stored= self._sqlite.load_narrative()

stored, updated_ts= self._sqlite.load_narrative_record()

if stored is not None and stored.size == self.v.size:

self.v = stored.astype(np.float32)

self._updated_ts = float(updated_ts or 0.0)

return

path = pathlib.Path(self.path)

arr = np.array(data.get("v", []), dtype=np.float32)

if arr.size == self.v.size:

self.v = arr

self._updated_ts = float(data.get("updated_ts", 0.0))

def _save(self) -> None:

now = time.time()

self._updated_ts = now

if self.backend == "memory":

return

if self.backend == "sqlite" and self._sqlite is not None:

with suppress(Exception):

self._sqlite.save_narrative(self.v)

path = pathlib.Path(self.path)

path.parent.mkdir(parents=True, exist_ok=True)

with suppress(Exception), path.open("w", encoding="utf-8") as handle:

json.dump({"v": self.v.tolist()}, handle)

json.dump({"v": self.v.tolist(), "updated_ts": now}, handle)

with suppress(Exception):

path.chmod(0o600)

docs_norm = safe_normalize(doc_embeddings)

sims = (v @ docs_norm.T).reshape(-1)

return sims.astype(np.float32)

def purge_if_stale(self, retention_seconds: float) -> None:

if retention_seconds <= 0:

return

cutoff = time.time() - retention_seconds

if self._updated_ts == 0 or self._updated_ts >= cutoff:

return

self.v = np.zeros_like(self.v, dtype=np.float32)

self._updated_ts = 0.0

if self.backend == "sqlite" and self._sqlite is not None:

with suppress(Exception):

self._sqlite.clear_narrative()

elif self.backend == "json":

path = pathlib.Path(self.path)

with suppress(FileNotFoundError):

path.unlink()

def refresh(self) -> None:

self._load()

self._load()

def _load(self) -> None:

if self.backend == "memory":

return

path = pathlib.Path(self.path)

if not path.exists():

return

def _save(self) -> None:

if self.backend == "sqlite" and self._sqlite is not None:

return

if self.backend == "memory":

return

path = pathlib.Path(self.path)

path.parent.mkdir(parents=True, exist_ok=True)

self.data[doc_id] = rec

if self.backend == "json":

self._save()

def purge_older_than(self, retention_seconds: float) -> None:

if retention_seconds <= 0:

return

if self.backend == "sqlite" and self._sqlite is not None:

self._sqlite.purge_older_than(retention_seconds)

return

cutoff = time.time() - retention_seconds

stale_keys = [

doc_id

for doc_id, rec in self.data.items()

if float(rec.get("t", 0.0)) < cutoff

]

for key in stale_keys:

self.data.pop(key, None)

if self.backend == "json":

self._save()

)

self._cr_index: CRIndex | None = None

storage_backend = (self.settings.storage_backend or "sqlite").lower()

if not self.settings.storage_persistence_enabled:

storage_backend = "memory"

storage_dir = Path(self.settings.storage_dir or ".")

storage_dir.mkdir(parents=True, exist_ok=True)

sqlite_state: SQLiteState | None = None

retention_seconds: float | None = None

if self.settings.storage_retention_days is not None:

retention_seconds = max(0.0, float(self.settings.storage_retention_days) * 86400.0)

if storage_backend == "sqlite":

db_path = storage_dir / self.settings.storage_db_name

sqlite_state = SQLiteState(path=str(db_path))

if retention_seconds:

sqlite_state.purge_older_than(retention_seconds)

self._sqlite_state = sqlite_state

self.narr = NarrativeTracker(

dim=self.settings.narrative_dim,

storage_dir=str(storage_dir),

sqlite_state=sqlite_state,

)

if retention_seconds:

self.narr.purge_if_stale(retention_seconds)

self.pher.purge_older_than(retention_seconds)

def _ensure_cr_loaded(self) -> CRIndex | None:

if not self.settings.cr.on: