AI Integration Guide

jinflow uses Claude (Anthropic) for two distinct capabilities: interactive analysis and finding explanations.

Setup

# Set API key (one-time, stored in ~/.jinflow/secrets.yml)
jin us --api-key sk-ant-api03-...

# Or via environment variable
export ANTHROPIC_API_KEY=sk-ant-api03-...

Both features share the same API key. No other configuration is required.

Two AI Modes

1. Evolve (Interactive Analysis)

jin evolve is a conversational REPL for AI-assisted data exploration. The AI has full access to the KLS, can write SQL, inspect signals, and help investigate findings.

Aspect	Detail
Command	jin evolve --tenant millesime.domaine_zufferey
Model	Claude Opus or Sonnet (configurable via jin us --model)
Context	Multi-turn conversation with data access
Cost	~$0.10–0.50 per conversation
Use case	Deep investigation, thesis exploration, signal design

The AI is scoped to exactly one tenant — it cannot query across tenant schemas.

2. Finding Explainer (One-Shot)

The “Explain in detail” button on finding detail pages generates a CFO-ready narrative from a single finding’s evidence.

Aspect	Detail
Trigger	Click “Explain in detail” on any finding
Model	Claude Haiku (fast, ~1-2 seconds)
Override	JINFLOW_AI_MODEL environment variable
Context	Single finding + entity attributes + signal metadata
Cost	~$0.01 per explanation
Use case	Quick narrative for presentations, audits, reports

The explainer enriches the finding with entity attributes from Gold and signal metadata from the registry before building the prompt. The response is rendered as Markdown.

Model Selection

Feature	Default Model	Override
Evolve	Configured via jin us --model	Per-session
Finding Explainer	claude-haiku-4-5-20251001	JINFLOW_AI_MODEL env var
Guide Translation	claude-haiku-4-5-20251001	JINFLOW_AI_MODEL env var

Privacy

• The AI sees only the data you send it — finding evidence, entity attributes, signal metadata
• Evolve is scoped to one tenant (enforced by the REPL)
• No data is stored by Anthropic (API usage, not training)
• The API key is stored locally in ~/.jinflow/secrets.yml (never in the repo)

Guide Translation

scripts/translate_guides.py uses Claude to translate guide markdown files from English to German and French. This runs as a build step, not at runtime.

python3 scripts/translate_guides.py           # translate changed guides
python3 scripts/translate_guides.py --check   # dry-run
python3 scripts/translate_guides.py --force   # retranslate everything

Translations are cached via SHA-256 manifest — unchanged source files are skipped.