Correct memories are not always transferable.

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

Define required slots

profiles:
  IncidentCommander:
    required_slots:
      - slot_name: blast_radius
        gap_type: blast_radius_gap
        description: Impacted users, systems, and time window are not explicit.
        question: Which users, systems, and time window are impacted?
        severity: HIGH
        high_risk: true
      - slot_name: rollback_owner
        gap_type: rollback_owner_gap
        description: The person or team authorized to trigger rollback is not explicit.
        question: Who is authorized to trigger rollback?
        severity: HIGH
        high_risk: true
      - slot_name: customer_message
        gap_type: customer_message_gap
        description: Customer-safe incident wording is not available.
        question: What customer-facing message should be used?
        severity: MEDIUM

Use the profile from CLI

handovergap detect \
  --scenario S001 \
  --profile IncidentCommander \
  --profile-file examples/profiles/incident_readiness.yml

The same profile can be used in Python with TransferabilityGate.from_profile_file(...).

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

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

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)

Run with a custom profile

from handovergap import TransferabilityGate

gate = TransferabilityGate.from_profile_file(
    "examples/profiles/incident_readiness.yml"
)
result = gate.check(
    memory="The checkout incident is mitigated by disabling the new queue worker.",
    profile="IncidentCommander",
    task_context="Decide whether customer-facing mitigation is complete.",
    evidence=["Rollback owner is on-call SRE. Blast radius is checkout only."],
    provided_slots=["rollback_owner"],
    evidence_slots=["blast_radius"],
)

for question in result.questions:
    print(question.question)

Prepare TiDB schema

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

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

Before answering

from handovergap import TransferabilityGate

gate = TransferabilityGate()

retrieved_memory = retriever.search(user_question)
evidence = retriever.search_evidence(user_question)

result = gate.check(
    memory=retrieved_memory.text,
    profile="CS",
    task_context="Answer the customer's question without overpromising.",
    evidence=[item.text for item in evidence],
    provided_slots=retrieved_memory.slots,
    evidence_slots=[slot for item in evidence for slot in item.slots],
)

if result.transferability_status != "transferable":
    return {
        "status": result.transferability_status,
        "reason": [gap.description for gap in result.gaps],
        "questions": [q.question for q in result.questions],
    }

return llm.answer(user_question, context=retrieved_memory.text)

What the gate returns

This pattern works for human handoff, support replies, incident response, sales renewal notes, and agent memory checks. The domain changes; the gate contract stays the same.