Skip to main content
Human-in-the-Loop (HITL) mode allows you to interactively review and edit the generated Logic Map and scenarios before trace generation.

​
Enabling HITL

import synkro

# HITL is enabled by default
dataset = synkro.generate(policy, traces=100)

# Explicitly enable
dataset = synkro.generate(policy, traces=100, enable_hitl=True)

# Disable for batch runs
dataset = synkro.generate(policy, traces=100, enable_hitl=False)

​
HITL Session Flow

  1. Logic Map Review: View extracted rules and categories
  2. Scenario Review: View generated scenarios with coverage
  3. Interactive Editing: Modify rules, scenarios, or coverage
  4. Confirmation: Approve to proceed with trace generation

​
Available Commands

During a HITL session, you can use these commands:

​
Logic Map Commands

CommandDescription
edit rule R001Edit a specific rule
add ruleAdd a new rule
remove rule R001Remove a rule
show rulesDisplay all rules

​
Scenario Commands

CommandDescription
edit scenario 1Edit scenario #1
add scenarioAdd a new scenario
remove scenario 1Remove scenario #1
regenerate scenariosRegenerate all scenarios
add 5 more scenariosGenerate 5 additional scenarios

​
Coverage Commands

CommandDescription
show coverageDisplay coverage report
increase coverage for [sub-category] by 20%Add scenarios to improve coverage
target [sub-category] to 80%Generate scenarios to reach target coverage

​
Session Commands

CommandDescription
continue / ok / doneProceed to next phase
quit / exitCancel generation
helpShow available commands

​
Example Session

Generating 100 traces | CONVERSATION | gpt-5-mini

Logic Map extracted with 12 rules:
  R001: [approval] Refunds over $100 require manager approval
  R002: [eligibility] 30-day return window for all items
  R003: [exception] Final sale items cannot be returned
  ...

[HITL] Review Logic Map (type 'help' for commands): edit rule R001

Editing R001: "Refunds over $100 require manager approval"
New text: Refunds over $50 require manager approval

[HITL] Review Logic Map: continue

Generating scenarios...

Coverage Report:
  Sub-Category                Coverage    Status
  Time-based eligibility      80% (4)
  Amount thresholds           60% (3)     ~
  Method restrictions         0% (0)

[HITL] Review Scenarios: increase coverage for Method restrictions by 40%

Generating 2 scenarios for Method restrictions...
Added 2 scenarios.

[HITL] Review Scenarios: continue

Generating traces...

​
Programmatic HITL with Session API

The Session API provides the cleanest way to do programmatic HITL with database persistence: 
from synkro import Session
from synkro.models import Google

# Create persistent session
session = await Session.create(
    policy="Expenses over $50 need manager approval...",
    session_id="my-session"
)
session.model = Google.GEMINI_25_FLASH

# Extract rules and refine with natural language
await session.extract_rules(session.policy)
await session.refine_rules("add rule: meals capped at $75/day")
await session.refine_rules("remove R005")

# Generate scenarios and refine
await session.generate_scenarios(count=30)
await session.refine_scenarios("add 5 edge cases for meal limits")

# Inspect state
print(session.show_rules())
print(session.show_distribution())

# Complete pipeline
dataset = await session.done(output="training.jsonl")

# Resume later
session = await Session.load_from_db("my-session")
See the Session API reference for full documentation.

​
Low-Level Programmatic HITL

For custom HITL flows without persistence, use the lower-level components: 
from synkro.advanced import LogicExtractor, ScenarioGenerator

# Extract logic map
extractor = LogicExtractor(llm)
logic_map = await extractor.extract(policy)

# Manual editing
logic_map.rules[0].text = "Modified rule text"

# Generate scenarios from edited logic map
generator = ScenarioGenerator(llm)
scenarios = await generator.generate(logic_map, count=100)

​
Disabling HITL for CI/CD

In automated pipelines, disable HITL: 
from synkro import create_pipeline, SilentReporter

pipeline = create_pipeline(
    enable_hitl=False,
    reporter=SilentReporter(),
)

dataset = pipeline.generate(policy, traces=1000)

​
Best Practices

  1. Review Logic Map First: Ensure rules are correctly extracted before generating scenarios
  2. Check Coverage: Use coverage report to identify gaps before proceeding
  3. Start Small: Review with 10-20 scenarios before scaling up
  4. Save Checkpoints: Use checkpoint_dir to save progress during long sessions
  5. Disable for Production: Use enable_hitl=False for batch/automated runs