Python library for handover-oriented RAG

Correct memories are not always transferable.

HandoverGap detects missing tacit context in otherwise correct RAG memories, checks the successor responsibility profile, and blocks unsafe transfer with clarification questions.

Start using it PyPI package 日本語README

HandoverGap Streamlit demo showing Japanese default UI, local sample mode, and Live OpenAI plus TiDB option

Install And First Run

1. Install

Use the latest tested release

The core package has no TiDB, OpenAI, or Streamlit runtime requirement.

pip install handovergap==0.1.4

2. Inspect one case

Run the built-in demo

See a valid memory that is unsafe to transfer without the successor's required context.

handovergap demo

3. Measure behavior

Compare baselines

Run the bundled synthetic benchmark against Naive, Hybrid, and HandoverGap RAG.

handovergap evaluate --compare

CLI Usage

Detect gaps for a handover profile

`detect` checks a built-in fictional scenario against a successor responsibility profile. `CS`, `Engineer`, and `Sales` are packaged presets, not a fixed industry taxonomy.

handovergap detect --scenario S001 --role CS

Evaluate slot-filling sensitivity

The holdout stress profiles simulate how semantic slot filling can under-fill or over-fill required context.

handovergap evaluate --dataset holdout --stress-filling

What It Adds To RAG

Approach	Optimizes	Misses
Naive RAG	Relevant memory retrieval	Whether a successor can safely act
Hybrid RAG	Evidence and risk warnings	Profile-specific missing context
Context engineering	Better prompt and context packaging	A durable audit trail for withheld answers
HandoverGap	Profile-required slot checks before answering	Production use still needs organization-specific annotation

Local And Live Demo

Default

Local bilingual Streamlit demo

The UI opens in Japanese by default and can switch to English. Local-sample mode runs the real deterministic detector on fictional handover cases.

pip install "handovergap[demo]"
handovergap serve

Optional

Live OpenAI + TiDB audit demo

Live OpenAI + TiDB mode asks the selected OpenAI model to fill profile-required slots, runs HandoverGap on those slots, and persists audit rows to TiDB.

pip install "handovergap[live]"
export OPENAI_API_KEY="..."
export TIDB_HOST="..."
export TIDB_USER="..."
export TIDB_PASSWORD="..."
handovergap serve

Live dependencies are optional by design. First-run usage, CI, and package import do not require an OpenAI key or TiDB account.

TiDB Audit Query

TiDB is used as more than a vector store. HandoverGap stores the decision path so a blocked answer can be explained across SQL rows, vector-backed evidence, JSON retrieval metadata, gaps, and questions.

handovergap audit-sql

The generated SQL joins transfer_assessments, memory_items, context_gaps, slot_fill_attempts, source_events, and clarification_questions. It answers: which required slot was missing, what evidence was checked, and what should be asked before handover.

Evaluation Snapshot

These are deterministic results from the bundled synthetic 20-scenario mini dataset. They demonstrate reproducible behavior, not production accuracy.

Method	Tacit Gap Recall	Unsafe Transfer Prevention	Question Coverage	Safe Transfer Allowance	Blocked Precision
naive_rag	0.00	0.00	0.00	1.00	0.00
hybrid_rag	0.21	0.59	0.21	0.67	0.91
handovergap	1.00	0.65	1.00	1.00	1.00

Live gpt-5-mini with the tuned gpt5_strict prompt reached tacit gap recall 1.00, unsafe transfer prevention 0.67, safe transfer allowance 1.00, and blocked precision 1.00 on the holdout protocol. See results notes.

Python API

Run the detector in code

from handovergap import HandoverGapDetector, InMemoryStore

store = InMemoryStore.from_builtin_dataset()
detector = HandoverGapDetector(store)
result = detector.detect(scenario_id="S001", successor_role="CS")

print(result.transferability_status)
print(result.gaps)
print(result.questions)

Prepare TiDB schema

Print the bundled schema locally or create it through the optional TiDB store.

pip install "handovergap[tidb]"
handovergap schema --dialect tidb

What This Page Helps Validate

PyPI first-run experience

Users can install the core package and run the MVP commands without secrets.

Demo clarity

The page shows the actual Japanese-default demo and its optional live path.

TiDB-specific learning

TiDB is used as a single audit store for slot attempts, evidence, gaps, questions, and transfer decisions.