Python library for profile-conditioned RAG readiness

Correct memories are not always transferable.

HandoverGap detects missing tacit context in otherwise correct RAG memories, checks the requested profile and task context, 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.6

2. Inspect one case

Run the built-in demo

See a valid memory that is unsafe to use without the selected profile'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 profile

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

handovergap detect --scenario S001 --profile 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

Retrieve slot evidence

Hybrid retrieval combines vector-style similarity and full-text matching before the gate decides whether the profile has enough context.

handovergap retrieve-evidence \
  --scenario S001 \
  --profile CS \
  --slot communication_status \
  --mode hybrid

Generate a report

Produce a reproducible Markdown report for the bundled mini, holdout, adversarial, and sanitized splits.

handovergap report --dataset all \
  --output reports/evaluation-latest.md

What It Adds To RAG

Approach	Optimizes	Misses
Naive RAG	Relevant memory retrieval	Whether a profile 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 operational 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 the answer is used.

Live TiDB validation	Observed
Dataset	sanitized
Persisted scenarios	6
Audit query rows	7
p50 latency	48.408 ms
p95 latency	1510.413 ms

This is a 10-iteration TiDB Cloud validation result for the audit query path, not a load-test claim. The p95 includes cold or variable cloud latency.

Generated workload on TiDB	Observed
Generated scenarios	100
Slot-fill attempts	567
Context gaps / questions	254 / 254
Audit query rows	254
p50 / p95 latency	38.818 ms / 574.713 ms

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	1.00	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 1.00, safe transfer allowance 1.00, and blocked precision 1.00 on the holdout protocol. See results notes.

The adversarial split keeps recall low at 0.38 but reduces false clarification to 0.00 after evidence-backed slot reconciliation. The sanitized split uses field-realistic anonymized CRM, incident, runbook, and deal-review style notes without real company data.

Python API

Run the gate in code

from handovergap import TransferabilityGate

gate = TransferabilityGate()
result = gate.check(
    memory="Use CSV for this release; API support is deferred.",
    profile="CS",
    task_context="Answer customer questions about the workaround.",
    evidence=["CSV workaround approved for the release."],
    provided_slots=["scope"],
    evidence_slots=["scope"],
)

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.