with:

name:coverage-xml-${{ matrix.python-version }}-${{ github.run_id }}

path:coverage.xml

smoke-eval:

runs-on:ubuntu-latest

needs:ci

steps:

-uses:actions/checkout@v4

-name:Setup Python

uses:actions/setup-python@v5

with:

python-version:'3.11'

-name:Install (runtime + ops extra)

run:|

-name:Launch API (background)

run:|

-name:Smoke eval (sample dataset)

run:|

-name:Show eval summary

if:always()

run:head -n 10 sample_eval.csv || true

-name:Stop API

if:always()

run:|

- SECURITY.md with disclosure process, supported versions guidance, and dependency audit integration (pip-audit)

- Optional extras separation clarified:`adapters`,`ops`,`embeddings` now explicitly documented in README

- README summary paragraph positioning NeuralCache as opinionated, stateful reranking layer

- Structured API success + error envelopes with standardized error codes (see README)

- Scoring pipeline specification (`docs/SCORING_MODEL.md`) detailing dense, narrative, pheromone, MMR, and exploration fusion formula

- Sample evaluation dataset (`data/sample_eval.jsonl`) for quick Context-Use@K smoke tests

- Build bootstrap hardening: enforce safe pip range excluding 25.2 (GHSA-4xh5-x5gv-qwph) and updated setuptools minimum

- CI workflow now upgrades both pip and setuptools prior to installation; pip-audit runs post-install

- Broadened dependency ranges (FastAPI, Starlette, Uvicorn) to reduce upgrade churn while retaining safety bounds

- Prevent accidental install of vulnerable pip version 25.2 by pinning`<25.2`

- Improved alignment between PyPI metadata and README summary

- Next minor (0.4.x) will introduce formal API versioning header, deterministic mode, standardized error envelopes, and scoring spec documentation (tracked in issues)

- Cognitive gating layer with entropy-aware candidate trimming and configuration overrides

The previous synthetic Context-Use demo is being redesigned. We’ll publish a refreshed walkthrough once the new baseline is validated. In the meantime you can point`scripts/eval_context_use.py` at your own JSONL datasets to measure uplift between any two rerankers.

We ship a small, neutral illustrative dataset at`data/sample_eval.jsonl` (5 queries) covering:

- Stigmergy concept recall

- MMR rationale

- ε-greedy exploration purpose

- Pheromone decay motivation

- Narrative memory function

Each line contains:

{"query":"...","docs": [{"id":"d1","text":"..."},...],"answer":"..."}

Run a smoke eval against a locally running API:

python scripts/eval_context_use.py \

--api http://127.0.0.1:8080 \

--data data/sample_eval.jsonl \

--out reports/sample_eval.csv \

--top-k 3

Inspect`reports/sample_eval.csv` for per-query hits. Extend by appending more JSONL lines that follow the same schema; avoid sensitive data—this file is published.

{"query":"What is stigmergy?","docs": [{"id":"d1","text":"Stigmergy is indirect coordination mediated by environment-modifying traces."}, {"id":"d2","text":"Reinforcement learning uses rewards to optimize actions."}, {"id":"d3","text":"Indirect coordination systems appear in social insects like ants."}, {"id":"d4","text":"A vector database stores embeddings for similarity search."}],"answer":"Stigmergy is indirect coordination via environmental traces."}

{"query":"Why apply MMR in reranking?","docs": [{"id":"d5","text":"MMR reduces redundancy by balancing relevance and diversity."}, {"id":"d6","text":"Cosine similarity measures angle between embedding vectors."}, {"id":"d7","text":"Diversity in retrieved contexts prevents repeated evidence."}],"answer":"To reduce redundancy; MMR balances relevance with diversity."}

{"query":"What does epsilon-greedy do?","docs": [{"id":"d8","text":"Epsilon-greedy occasionally explores random candidates."}, {"id":"d9","text":"Exploration helps avoid local optima in adaptive systems."}, {"id":"d10","text":"Embedding models map text into vector space."}],"answer":"It occasionally explores alternatives (epsilon-greedy) to avoid local optima."}

{"query":"Why decay pheromones?","docs": [{"id":"d11","text":"Pheromone decay prevents stale documents from dominating."}, {"id":"d12","text":"EMA narrative memory emphasizes recent successful context windows."}, {"id":"d13","text":"Caching strategies can include LRU or LFU."}],"answer":"Decay prevents stale documents from dominating future reranks."}

{"query":"What is narrative memory?","docs": [{"id":"d14","text":"Narrative memory tracks successful multi-turn context windows with an EMA."}, {"id":"d15","text":"Transformers use self-attention to model token dependencies."}, {"id":"d16","text":"SQLite provides transactional persistence for small apps."}],"answer":"It tracks successful multi-turn context windows (EMA narrative memory)."}