AI Architecture
Local Intelligence — on-device reasoning for craft, not cloud résumé farming.
Parent: OVERVIEW.md · Package: packages/ai · Terms: ../product/TERMINOLOGY.md
Thesis
AI in JobJitsu helps draft, tailor, queue, and remind. It does not guarantee interviews or own the send button. The primary path is a user-provided local LLM (and local embeddings when used). Status chrome (Agent · On-device) must reflect provider locality honestly.
Components
| Component | Role |
|---|---|
| AI Provider | health, complete, embed (optional) — swappable runtimes |
| Model Manager | Load / select / unload / monitor models for providers (lives in packages/ai) |
| Local adapters | Bind to on-device runners (user model path / runtime) |
| Remote adapters | Optional, explicit user config only; never labeled Agent · On-device |
| Context Builder | Assembles minimal prompts (alias: context assembler) |
| AI Validation | Post-generate gates — see “Workflow engine” below |
| Prompt roles | Tailor, match explain, follow-up draft, parse assist |
| Tool bridge | Safe tools to Agent / Plugins via host |
| Status publisher | Emits Ai.LocalModel* / Ai.Started / Ai.Finished for chrome |
Provider contract (conceptual)
health()→ ready | loading | unavailable | misconfiguredcomplete(request)→ text/structured result; runs where configuredembed(texts)→ vectors for local search (stored on-device)
Providers must not phone home with résumé text unless the user selected a remote endpoint knowingly.
Context Builder
Canonical term: Context Builder. Default slice order for apply-craft: Profile → Resume → Projects → Achievements → Current Job → Prompt → Model (budgeted by task). Retrieves from Knowledge Base when available via a KnowledgeReader port (implemented by identity; ai must not own knowledge writes). Core ships createContextAssembler + createNoopKnowledgeReader in @jobjitsu/ai (PE05-S03). See DATA_MODELS.md.
| Task | Typical context |
|---|---|
| Tailor cover letter | Résumé excerpts, role description, tone prefs |
| Fit note | Skills vs requirements (short) |
| Follow-up draft | Prior send metadata, polite tone prefs |
Avoid dumping entire Timeline history into every prompt. No hidden training export.
Agent ↔ AI relationship
- Agent Workflow Engine plans steps; AI executes language/embedding tasks inside Running Task Queue items.
- Tools that mutate drafts go to Applications / review Queue.
- Tools that would egress are not exposed to AI — only through policy → Queue → Send.
✅ GOOD: AI produces tailored draft → validation → Queue.Enqueued
❌ BAD: AI tool “submitApplication” with network socket
Workflow engine (design contract — not yet built)
When agent orchestration lands (packages/agent), it follows this shape. A Workflow is a declarative step list (validate | analyze | retrieve | generate | prepare | await_approval | egress_intent | persist | cleanup); the AI Task Queue runs steps with default concurrency 1 (states: Pending / Running / Waiting / Completed / Failed / Cancelled). Laws that survive into any implementation:
egress_intentmay only enqueue review-Queue items or emit send intents — never callsend.executeor the network.Agent.Pausedcancels/freezes Running tasks, retains Pending, and leaves the review Queue intact.- Generated artifacts pass AI Validation (formatting → ATS → missing skills, deterministic checks preferred) before reaching the review Queue; bounded repair retries, then wait for the user.
- Models unload after drain or idle. The AI Task Queue is never conflated with the user-facing review Queue.
Events: Workflow.Started|Completed|Failed, Ai.Started|Finished, Ai.ValidationCompleted (EVENT_SYSTEM.md).
Honest AI product rules
- Status chrome shows Agent · On-device only when the active provider is local.
- Remote providers labeled plainly (e.g. “Remote model — user configured”).
- Failures use plain recovery (
Ai.LocalModelFailed→ Preferences local model path). - Outputs are suggestions; user remains author of final voice.
- Resource failures: calm copy (“On-device model ran out of resources”).
- Missing/misconfigured
settings.ai.localModelPathkeeps Agent unavailable — no silent remote fallback;health()does not load weights. - PE05-S06: Desktop host uses
createOllamaAiProvider(loopback only). Prefs store an Ollama model name (e.g.qwen2.5:3b). Free install guide:docs/guides/LOCAL_AGENT_MODELS.md. Vitest keeps the fake provider.
Embeddings & local retrieval (optional)
- Indexes under local storage; used for Knowledge / résumé section retrieval; not uploaded.
Performance
- Lazy-load weights; honor
Agent.Paused; unload after Task Queue drain / idle.
Security
- User-controlled model path; JD treated as untrusted; logs redact prompt bodies by default.
Out of scope
- Fine-tuning on user data in a JobJitsu cloud; default vendor cloud LLM; autopilot send from model confidence.
