Intelligent multi-agent conversational assistant with LangGraph orchestration, Human-in-the-Loop, enterprise-grade observability, and full i18n support (6 languages)
If you find my project and work valuable, I would be grateful for a star on GitHub. Thank you !
Features • Admin & Monitoring • Quick Start • Architecture • Documentation • Contributing
Version 1.25.5 — The phone assistant becomes trustworthy — and the planner learns to converge. A full day of live-call debugging turns agentic telephony from a promising prototype into a disciplined agent. On the call: an instant localized greeting at pickup (an empty first message caused a multi-second silent standoff), a current_datetime
anchor so "tomorrow" resolves to the right weekday out loud, a pinned multilingual voice over telephony-native ulaw_8000
audio, a pinned thinking-free LLM (the platform default was caught reciting its English reasoning aloud mid-call), and a real hang-up via the end_call
system tool. Above all, a mandate boundary: the assistant never accepts an unrequested expense or commitment — even a 3€ topping — it captures the offer and its price, defers to the user, and the post-call summary must state every cost and flag every open point for a call-back. Around the call: the vendor agent re-syncs lazily on config drift (no more deactivate/reactivate), a stuck "call already active" row self-heals by probing the vendor (including the deleted-agent 404 case, grace-window protected), and vendor errors are diagnosable in one log line. In the pipeline: the post-call follow-up "crée le rdv" kept producing a next-hour default slot instead of the agreed Saturday 9:30 — resolved facts now ride in the planner's human message where models actually read them; the semantic validator finally validates single-step mutations (skipped as "trivial" before — the whole class was unguarded), survives a structured-output prompt conflict with an A/B-proven fix (0/3 → 6/6 tool calls) plus a one-shot retry, rejects fabricated placeholder emails deterministically (RFC 2606), and on replan the planner is finally shown its own previous plan with a fix-don't-rebuild directive (it used to oscillate — fixing the date on one pass, losing it on the next). Final net: an invalid mutation plan that exhausts its replans is never silently executed — LIA asks the user instead. Verified: 10,344 fast unit tests green, mypy strict clean on 900 files, every fix reproduced then re-proven against live prod logs and real calls. — 17 July 2026.
Why LIA?Try LIA OnlineBuilt by an AI, Directed by a HumanScreenshotsFeaturesAdministration & MonitoringQuick StartArchitectureTechnologiesDocumentationTestsCI/CDPerformanceSecurityContributingSupportLicenseAcknowledgments
LIA solves the fundamental problems of today's AI assistants:
| Problem | LIA Solution |
|---|---|
| Unpredictable LLM costs | |
| Real-time token tracking, budget alerts, 93% optimization | |
| Uncontrolled hallucinations | |
| Human-in-the-Loop (HITL) with 6 approval levels | |
| Fragmented integrations | |
| Unified multi-domain orchestration (19+ agents + MCP + sub-agents) | |
| Limited observability | |
| 419 Prometheus metrics, 25 Grafana dashboards, email alerting with runbooks, GeoIP analytics | |
| Inconsistent performance | |
| Gemini embedding-001 with asymmetric task types, semantic routing with hybrid scoring |
📅 "Find my meetings for tomorrow and send a reminder to all participants"
📧 "Summarize my unread emails from this week that have attachments"
👥 "Update the companies of my contacts who work at startups"
🔔 "Remind me tomorrow at 9am to call Marie for her birthday"
LIA is available as a hosted service at ** https://lia.jeyswork.com/** — no installation required.
Closed beta: Access is currently limited to a restricted number of users, at the administrator's discretion. To request an invitation, contact.[liamyassistant@gmail.com]
"Speed comes from the AI. Quality comes from the framework."
Nearly 100% of this codebase was written by an AI, under human direction: a written engineering rulebook, blocking automated checks, systematic review, adversarial audits. The result is measured, not proclaimed:
32 functional domains | 420,000 lines of code (excl. tests) | 11,900+ automated tests | 120+ ADRs | 153 versions shipped | 6 languages, parity enforced in CI | 419 Prometheus metrics | 8.3/10 technical audit, 24 normalized areas |
The full story— method, trade-offs, results and what remains to be done, weaknesses included:lia.jeyswork.com/storyThe audit itself— 24 normalized areas mapped to ISO/IEC 25010:2023, every score backed by executed evidence, 7 open worksites included, with the protocol and the full standalone report:docs/audit/
Dashboard — Homepage with quick access, usage statistics, and personalized greeting
Chat — Multi-agent conversation with real-time debug panel (right sidebar)
More screenshots
Chat — Debug panel: per-message routing, tool calls, token cost and reasoning timeline
Chat — Interactive skill widgets: maps, dashboards, calendars and mini-apps rendered inline
Settings — Preferences: connectors, MCP servers, language, timezone, and themes
Settings — Features: LIA Style, long-term memory, interests, proactive notifications, scheduled actions, sub-agents, channels
Settings — Long-term memory: pinned facts, automatic extraction, edit / delete / pin per memory
Settings — Psyche Engine: Big Five personality traits modulating the assistant's emotional responsiveness
Settings — Administration: LLM config, RAG Spaces, users, connectors, pricing, skills, voice, broadcast, debug
Administration — One-click simplicity: every admin action is accessible in a single click, no technical skills required
Administration — LLM Configuration: 7 providers (OpenAI, Anthropic, Google Gemini, DeepSeek, Qwen, Perplexity, Ollama), per-node model selection
19+ Specialized Agents: Contacts, Emails, Calendar, Drive, Tasks, Reminders, Places, Routes, Weather, Wikipedia, Perplexity, Brave, Web Search, Web Fetch, Browser Control (with progressive screenshot streaming), Smart Home (Philips Hue), Context, Query + dynamic MCP agentsReAct Execution Mode(ADR-070): Alternative to the pipeline — the LLM iteratively reasons about tool outputs and decides next steps autonomously. User-toggleable preference, 4-node LangGraph architecture with native HITL support, timeout enforcement, cross-domain initiative via prompt engineering. Supports all tools including MCP and SkillsMCP (Model Context Protocol): Per-user external tool servers with OAuth 2.1, SSRF protection, structured items parsing, MCP Apps (interactive iframe widgets),Iterative Mode (ReAct) for complex servers — a dedicated agent reads docs then calls tools correctlyAgent Initiative Phase: Post-execution cross-domain enrichment — the assistant proactively verifies related information (e.g., weather shows rain → checks calendar for outdoor events). Prompt-driven, read-only, fully configurableSkills (agentskills.io) with Rich Outputs: Open standard for expert instructions (SKILL.md), model-driven activation, progressive disclosure (L1/L2/L3), sandboxed scripts, marketplace import, auto-translated multi-language descriptions, ZIP download, admin management.Rich Skill Outputs(v1.16.8): skills can return interactive HTML frames (iframe srcDoc or external URL) and/or images in addition to text, via a simple JSON contract (SkillScriptOutput
). Automatic theme & locale sync (theme switch propagates live to frames viapostMessage
), iframe auto-resize, CSP-sandboxed client-side interactivity (addEventListener
,crypto.getRandomValues
), bundledsegno
for QR codes. Seven built-in rich skills:interactive-map
,weather-dashboard
,calendar-month
,qr-code
,pomodoro-timer
,unit-converter
,dice-roller
.Planner skill guard: multi-domain deterministic skills are protected from false-positive early clarification requests via domain overlap detection (_has_potential_skill_match
).Built-in Skill Generator: create custom skills in natural language — the assistant guides you through need analysis and archetype selection (the dialogue keeps its context across turns), then validates andinstalls the finished skill directly into My Skills, announced by name and immediately usable. Every import path (chat-generated or manual upload) goes through one hardened pipeline: strict name validation, zip-expansion caps, name-conflict rejection, atomic install with automatic rollbackAgentic Telephony(ADR-127): LIA places real outbound phone calls on your behalf via your own per-user ElevenLabs + Twilio connector (BYO — zero cost on LIA's side). Every call is HITL-confirmed before dialing; the goal-driven voice agent greets the instant the line opens, resolves relative dates against a live temporal anchor, and hangs up when done. Privacy by capability: the call agent can only read free/busy availability — never event titles or contents; no recording, no stored transcript. Astrict mandate boundary forbids any expense or commitment beyond the objective (offers are captured with their price and deferred to you), and the asynchronous post-call summary must state every cost and flag every open point. Config self-heals: fingerprint-based lazy re-sync of the vendor agent, self-healing one-active-call guard (vendor status probe, deleted-conversation 404 handling), pinned thinking-free agent LLM, telephony-nativeulaw_8000
audioAI Image Generation & Editing: Generate images from text prompts (gpt-image-1), edit existing images with natural language instructions. Multi-provider factory architecture, per-user quality/size preferences, cost tracking with DB-cached pricing, attachment-based storage with cascade cleanupFile Attachments (Images, PDF): Upload with client-side compression, configurable LLM vision analysis, PDF text extraction, strict per-user isolation** Semantic Routing**: Binary classification with confidence scoring (high >0.85, medium >0.65)** Multi-Step Planning**: ExecutionPlan DSL with dependencies and conditions** Parallel Execution**: asyncio.gather for independent domains** Intelligent Context Compaction**: LLM-based conversation history summarization when token count exceeds dynamic threshold (ratio of response model context window). Preserves identifiers (UUIDs, URLs, emails)./resume
command for manual trigger. 4 HITL safety conditions prevent compaction during active approval flowsScroll-up History Pagination:GET /conversations/me/messages
exposes a keyset cursor (?before=<created_at>
) withhas_more
/next_cursor
. The chat UI binds anIntersectionObserver
on a top sentinel — older pages prepend with id-based dedup, scroll position preserved via a sharedwasPrependRef
that skips the auto-scroll-to-bottom for that cycle. Conversations of any length stay fully reachable; the existing(conversation_id, created_at DESC)
composite index makes each page an index-only seek. Bounds env-tunable (CONVERSATION_HISTORY_DEFAULT_LIMIT
/_MAX_LIMIT
)
5-Layer Psychological State: Big Five personality traits (permanent) → PAD mood space with 14 moods (hours) → 22 discrete emotions with cross-suppression (minutes) → 4-stage relationship progression (weeks) → curiosity/engagement drives (per-session)Show, Don't Tell: Mood and emotions subtly influence word choice, sentence rhythm, energy level, and relational tone — the assistant never declares "I'm feeling happy"Emotional Avatar: Mood-responsive emoji with colored ring on each message. Historical avatars persisted per-message for reload consistencyEvolution Awareness: The assistant knows how its mood shifted since the last message, providing narrative continuity** 4-Chart Dashboard**: Interactive recharts visualization of mood (PAD), emotions, relationship, and drives over time (24h to 90 days)** Education Guide**: 7-section interactive documentation explaining every layer, with descriptive tables for 14 moods and 22 emotions** Customizable Temperament**: Expressiveness (stoic → highly expressive) and stability (volatile → very stable) sliders. Soft reset (mood only) and full reset (everything) with explicit scope descriptionsGlobal Injection: Behavioral directives injected via template variables into all user-facing text generation (response, notifications, reminders, voice) within semantic XML blocks (<InnerState purpose="tone-calibration">
)Safety Guardrail: Explicit instruction prevents the LLM from projecting its own emotional state onto the user** Self-Report**: Zero-cost emotion tracking via hidden<psyche_eval/>
tag — no additional LLM call
Voice Input (STT)
Push-to-Talk: Hold microphone button to speak, release to transcribe. Optimized for mobile (anti-long-press CSS, touch gesture handling)Wake Word: Say "OK Guy" to activate hands-free recording. Sherpa-onnx WASM (Whisper Tiny.en) runs entirely in-browser — no audio sent externally for wake word detectionPer-User Language: STT transcription uses the user's preferred language setting (Whisper Small, 99+ languages, fully offline)** Latency Optimized**: Mic stream reuse, WebSocket pre-warming, parallel setup, cached AudioWorklet (~50-100ms wake-to-record)
Voice Output (TTS)
| Provider | Models | Cost | Latency (TTFA) | Notes |
|---|---|---|---|---|
| Edge TTS (Microsoft Neural) | edge-tts |
|||
| Free | ~250 ms | Multilingual neural voices, free fallback | ||
| OpenAI TTS | tts-1 / tts-1-hd |
|||
| $15 / $30 per 1M chars | ~500 ms | 6 stable voices (alloy, echo, fable, onyx, nova, shimmer) | ||
| ElevenLabs TTS | eleven_multilingual_v2 |
|||
| $100 / 1M chars | ~300 ms | High-quality multilingual, Voice Library access | ||
eleven_turbo_v2_5 |
||||
| $50 / 1M chars | ~250 ms | Sweet-spot quality / latency | ||
eleven_flash_v2_5 |
||||
| $50 / 1M chars | ~75 ms | Ultra-low-latency for conversational agents |
Catalogue-driven(ADR-081): provider/model/voice are admin-controlled via Configuration LLM (LLM typevoice_tts
). Voice + tuning live inprovider_config
JSONB. No env vars to maintain across deployments.Sentence streaming(ADR-082): TTS runs sentence-by-sentence pipelined with the LLM stream. First audio lands in ~1 s on chat mode (was ~5 s).Per-message cost transparency:🔊 N chars · €X.XXX
badge on the assistant bubble (paid providers only — Edge stays badge-free as it's $0).Graceful degradation: missing API key on a paid provider transparently falls back to Edge with a structured warning log.** Persistent HTTP pool**on ElevenLabs: keep-alive across sentences saves ~100–300 ms TLS handshake per call.
ExecutionStep(
tool_name="send_email",
for_each="$steps.get_contacts.contacts",
for_each_max=10
)
HITL Thresholds: Mutations >= 1 trigger mandatory approval** Bulk Operations**: Send emails, update contacts, mass deletions
| Service | Role | Optimization |
|---|---|---|
| QueryAnalyzerService | Routing decision | LRU Cache |
| SmartPlannerService | ExecutionPlan generation | Pattern Learning |
| SmartCatalogueService | Tool filtering | 96% token reduction |
| PlanPatternLearner | Bayesian learning | Bypass >90% confidence |
Gmail: Search, read, send, reply, trash** Contacts**: Fuzzy search, list, details (14+ schemas)** Calendar**: Search, create, update events** Drive**: Search, file/folder listing** Tasks**: Full CRUD with completion
Apple Mail: Search, read, send, reply, forward, trash (IMAP/SMTP)** Apple Calendar**: Search, create, update, delete events (CalDAV)** Apple Contacts**: Search, list, create, update, delete (CardDAV)
Outlook: Search, read, send, reply, forward, trash (Graph API)** Calendar**: Search, create, update, delete events (calendarView)** Contacts**: Search, list, create, update, delete** To Do**: Full CRUD with completion (task lists + tasks)** Multi-tenant**: Personal accounts (outlook.com) and business accounts (Azure AD) viatenant=common
- Only one provider per functional category (email, calendar, contacts, tasks)
- 3 supported providers: Google, Apple, Microsoft
- Activating a new provider automatically deactivates the active competitor
Voice-controlled lighting: Turn lights on/off, adjust brightness and colors via natural language** Room & scene management**: Control entire rooms or activate predefined scenes ("dim the living room", "activate movie mode")** Local or cloud connection**: Connect via local bridge IP or Philips Hue cloud API** Feature flag**:PHILIPS_HUE_ENABLED=true
to enable
| Type | Trigger | Severity |
|---|---|---|
| Plan Approval | Destructive actions | CRITICAL |
| Clarification | Detected ambiguity | WARNING |
| Draft Critique | Email/Event review | INFO |
| Destructive Confirm | Deletion of >= 3 items | CRITICAL |
| FOR_EACH Confirm | Bulk mutations | WARNING |
| Modifier Review | Review and approve AI-suggested modifications to draft content | INFO |
Note: the plan-approval level is currently auto-approved — tool-level HITL supersedes it (see
[ADR-106]); the other five levels interrupt execution and wait for the user.
Prometheus: 419 custom metrics (agents, LLM, infrastructure)** Grafana**: 22 production-ready dashboards** Langfuse**: LLM-specific tracing with prompt versions** Loki**: Structured JSON logs with PII filtering** Tempo**: Distributed cross-service tracing** Probes**: liveness (GET /health
, always 200 while the process serves — what Docker healthchecks poll) split from readiness (GET /ready
, 503 unless PostgreSQLand Redis answer) —ADR-115Alerting: a 13-alert vital core (service/DB/Redis down, disk, container OOM, 5xx rate, SSE latency, backup failure, public-endpoint & TLS-certificate probes, chain self-monitoring) evaluated by Prometheus and emailed by a dedicated Alertmanager — unit-tested withpromtool test rules
, every alert linking its runbook —ADR-119
| Type | Tracking | Export |
|---|---|---|
| LLM Tokens | ||
| Per node, per provider | Detailed CSV | |
| Google API | ||
| Per endpoint, per user | Detailed CSV | |
| Aggregated | ||
| Per user, per period | CSV summary |
Google Maps Platform: Places, Routes, Geocoding, Static Maps** Dynamic Pricing**: Admin UI for full LLM catalogue CRUD — provider, 8 capability flags (max input/output tokens, tools, structured output, strict mode, streaming, vision, reasoning) and pricing per model, all stored in the database. Same surface for image generation models (provider + quality/size/pricing). Cross-worker cache invalidation via Redis Pub/Sub (ADR-063), live cross-sibling refresh in the frontend — no code change, no redeployContextVar Pattern: Implicit tracking without explicit parameter passing** Admin CSV Exports**: Token usage, Google API usage, Consumption summary (all users or filtered by user)** User CSV Exports**(v1.9.1): Personal consumption export in Settings > Features — users export their own data only (user_id
forced server-side, IDOR-safe)
OAuth 2.1: PKCE (S256), single-use state token** BFF Pattern**: HTTP-only cookies, Redis session with 24h TTL** Encryption**: Fernet (credentials), bcrypt (passwords)** GDPR**: Automatic PII filtering, pseudonymization, personal data export (Art. 20 data portability)** Per-User Usage Limits**: Token, message, and cost quotas (period/global) with 5-layer defense-in-depth enforcement, admin kill switch, real-time dashboard with WebSocket gauges. Feature flag:USAGE_LIMITS_ENABLED=true
Backups: Automated daily PostgreSQL dumps (pg_dump sidecar, daily/weekly/monthly rotation, all.env
-driven) with a tested one-command restore and a verification drill (task backup:verify
) — ADR-109, runbook indocs/runbooks/DATABASE_BACKUP_RESTORE.md
Per-user external servers: Each user connects their own MCP servers (third-party tools)** Flexible authentication**: None, API Key, Bearer Token, OAuth 2.1 (DCR + PKCE S256)** Enhanced security**: HTTPS-only, SSRF prevention (DNS resolution + IP blocklist), encrypted credentials (Fernet)** Structured Items Parsing**: Automatic JSON array detection into individual items with McpResultCard HTML** Auto-generated descriptions**: LLM analysis of discovered tools to generate domain descriptions optimized for intelligent routing** Per-server rate limiting**: Redis sliding window per server/tool** Feature flag**:MCP_USER_ENABLED=true
to enable per-user
Bidirectional Telegram: Full chat with LIA via Telegram (text, voice, HITL)** OTP Linking**: Secure account-to-Telegram linking via 6-digit OTP code (single-use, 5min TTL, brute-force protection)** HITL Inline Keyboards**: Approval/rejection buttons localized in 6 languages directly in Telegram** Voice Transcription**: Telegram voice messages to STT (Sherpa Whisper) to text processing** Proactive Notifications**: Reminders and interest alerts also sent via Telegram** Extensible Architecture**:BaseChannelSender
/BaseChannelWebhookHandler
abstraction for future channels (Discord, WhatsApp)Observability: 12 dedicated Prometheus RED metrics (latency, errors, volumes)** Feature flag**:CHANNELS_ENABLED=true
to enable
LLM-driven proactivity: LIA takes the initiative to inform you when relevant (weather, calendar, interests)** Multi-source aggregation**: Calendar, Weather (with change detection), Tasks, Interests, Memories, Activity — parallel fetch** 2-phase LLM decision**: Phase 1 (structured output, cost-effective model) decides whether to notify, Phase 2 rewrites with user personality and languageIntelligent anti-redundancy: Recent history + cross-type dedup (heartbeat vs. interests) in the decision prompt** User control**: Push notifications (FCM/Telegram) independently toggleable, configurable daily max (1-8), dedicated time windows (independent from interests)Weather change detection: Rain start/end, temperature drops, wind alerts — truly actionable notifications** Feature flag**:HEARTBEAT_ENABLED=true
to enable
Recurring actions: Schedule repetitive actions executed automatically (send emails, checks, reminders)** Timezone-aware**: Correct timezone handling per user** Retry logic**: Automatic retries on failure with back-off** Auto-disable**: Automatic deactivation after N consecutive failures** Multi-channel integration**: Result notifications via FCM, SSE, and Telegram** Feature flag**:SCHEDULED_ACTIONS_ENABLED=true
to enable
Persistent specialized agents: Create sub-agents with custom instructions, skills, and LLM configuration** Read-only V1**: Sub-agents perform research, analysis, and synthesis — no write operations** Template-based creation**: Pre-defined templates (Research Assistant, Writing Assistant, Data Analyst)** Invisible to user**: The principal assistant orchestrates sub-agents and presents results naturally** Token guard-rails**: Per-execution budget, daily budget, auto-disable after consecutive failures** Feature flag**:SUB_AGENTS_ENABLED=true
to enable (default: false)
Personal knowledge bases: Create spaces, upload documents in 15+ formats (PDF, DOCX, PPTX, XLSX, CSV, RTF, HTML, EPUB, and more), automatic chunking and embeddingGoogle Drive folder sync: Link Google Drive folders to spaces for automatic file vectorization with incremental change detection (new, modified, deleted). Feature flag:RAG_SPACES_DRIVE_SYNC_ENABLED
Hybrid search: Semantic similarity (pgvector cosine) + BM25 keyword matching with configurable alpha fusion** Response enrichment**: RAG context automatically injected into assistant responses when active spaces exist** Full cost transparency**: Embedding costs tracked per document and per query, visible in chat bubbles and dashboard** System knowledge spaces**: Built-in FAQ knowledge base (119+ Q/A across 17 sections) indexed from Markdown files (docs/knowledge/
).is_app_help_query
detection by QueryAnalyzer, RoutingDecider Rule 0 override, App Identity Prompt injection with lazy (zero overhead on normal queries). Auto-indexed at startup with SHA-256 hash-based staleness. Admin UI for reindex and staleness monitoring.ADR-058Admin reindexation: Full reindex when embedding model changes, with Redis mutual exclusion and automatic dimension ALTER. System spaces have independent reindex via admin APIObservability: 17 Prometheus metrics (14 user + 3 system), dedicated Grafana dashboard** Feature flags**:RAG_SPACES_ENABLED=true
(user spaces),RAG_SPACES_SYSTEM_ENABLED=true
(system FAQ spaces)
Introspective notebooks: The assistant maintains thematic journals (self-reflection, user observations, ideas & analyses, learnings) written in first person, colored by its active personalityFour abstraction levels: Each entry carries alevel
—L0
raw observation,L1
operational directive (WHEN→DO BECAUSE
),L2
transversal pattern,L3
portrait facet. L2/L3 are produced exclusively at consolidation through active topic clustering (ADR-079)Epistemic status:confidence
∈ {low, medium, high} plusevidence_count
andcontradiction_count
counters per entry. The journal distinguishes hypotheses still in test from observations validated across many turnsDeferred self-evaluation T → T+1:MessagesState.injected_journal_ids
carries IDs across turns; the post-conversation extractor sees the previous turn's directives + the current user reaction, signalsevidence_outcome="evidence" | "contradiction"
, and the service atomically increments the counters.Zero added LLM cost(same extractor call, enriched prompt). Anti-hallucination layer 4: LLM never writes absolute counter values.** Dual trigger**: Post-conversation extraction (fire-and-forget) + periodic consolidation (APScheduler, 4–12 h cooldown)** Gemini dual-vector embeddings**:gemini-embedding-001
(1536d) — one vector on title+content, one onsearch_hints
keywords. Search usesLEAST(dist_content, dist_keyword)
per row to bridge the assistant's introspective vocabulary and the user's vocabulary (ADR-069)Ambient diffusion of the user-model portrait: Consolidation produces, in the same LLM call, aportrait_full
(~200 tokens) for conversation/planner and aportrait_brief
(~60 tokens) diffused across 6 secondary flows (ReAct setup, interest proactive, reminder notification, voice, heartbeat, fallback sync+async). Standalone builderbuild_journal_user_model_block(user_id, format, flow)
mirrorsbuild_psyche_prompt_block
.Three corrective levers on the portrait (never directly editable): edit L3 source entries,POST /journals/portrait/feedback
(free text → L0user_correction
- synchronous re-consolidation),
POST /journals/consolidate
(manual, bypasses cooldown).Prompt-driven lifecycle: The assistant manages its own journals — no hardcoded auto-archival. Mandatory pairwise dedup at consolidation STEP 1, classification audit, active L1→L2 clustering at STEP 5Heartbeat integration: Journal entries enrich proactive notifications via dynamic second-pass query built from aggregated context. The compiled portrait brief is also injected so the notification voice is aligned with the same user model used by conversationFull user control: Enable/disable (data preserved), consolidation toggle, conversation history analysis (with cost warning), 4 configurable numeric settings, group-by Theme/Level toggle, filter "show only entries never used", full CRUD in Settings (level + confidence editable)4-layer anti-hallucination: prompt guidance with ID reference tables,field_validator
on UUIDs, known-ID filtering in extraction and consolidation, atomic counter increments11 Prometheus metrics:journal_entries_total{action,theme,source}
,journal_evidence_total{outcome}
,journal_consolidation_promotions_total{from_level,to_level}
,journal_level_distribution{level}
,journal_portrait_present_total{flow,format}
,journal_portrait_age_hours
,journal_portrait_feedback_total{outcome}
, etc.Debug panel: Dedicated "Personal Journals" section showing injection metrics AND background extraction results (CREATE/UPDATE/DELETE badges with theme/title/mood, even on partial updates where the LLM omits fields)Cost transparency: Real token costs tracked via TrackingContext, visible in Settings and dashboard** GDPR**: Account deletion scrubs the three portrait columns alongside entries; export endpoint includes the compiled portrait under aportrait
keyFeature flags:JOURNALS_ENABLED=false
(system), user-level toggle in Settings > Features. ADRs:ADR-057→ADR-064→ADR-069→ADR-079
Two token-authenticated endpoints(POST /api/v1/ingest/health/steps
and/api/v1/ingest/health/heart_rate
): an iPhone Shortcut automation pushes daily batches of samples. Each sample carries its own ISO 8601date_start
/date_end
— UTC-normalized server-side and second-truncated to keep uniqueness stable.Polymorphic single-table storage(health_samples
): one row per sample with akind
discriminator (heart_rate
|steps
). Extending tospo2
/sleep
/calories
reduces to a newkind
value — no new table, no new endpoint.Idempotent UPSERT(ON CONFLICT (user_id, kind, date_start, date_end) DO UPDATE
) using PostgreSQL'sRETURNING (xmax = 0)
trick to split insert vs update counts in a single round-trip. Re-sending the same batch is free — last value wins.Flexible body parser: accepts JSON array, NDJSON,{"data": [...]}
envelope, and the iOS Shortcuts "Dictionnaire" wrapping ({"<ndjson_blob>": {}}
) — no contract pressure on the user's Raccourci authoring.Per-user hashed tokens: SHA-256 digest stored, raw value (hm_xxx
) returned once at generation, display prefix shown in Settings, individually revocable. Multiple tokens may coexist for rotation.Mixed per-sample validation: out-of-range / malformed / missing-field / invalid-date samples are individually rejected with their 0-based index + reason, while valid siblings in the same batch persist.Bucketed aggregation(hour / day / week / month / year
): heart rate averaged (plus min / max), steps SUM-ed per bucket; gaps kept (has_data=False
) so the UI displays honest curves.Settings visualization: four-section panel (ingestion API + tokens, recharts line/bar charts with period average overlays, statistics, deletion by kind or full wipe).GDPR-aware: deletion by kind (DELETE ?kind=...
), full erasure (DELETE /all
),ON DELETE CASCADE
on the user FK.Observability: bounded-cardinality Prometheus metrics (health_samples_upserted_total{kind, operation}
, validation rejections, rate-limit hits, auth failures, token lifecycle, deletions, latency histogram) + Grafana dashboard 21.Guards: 60 req/h/token sliding-window rate limit (configurable), 1000 samples/batch cap (413
beyond).Feature flag:HEALTH_METRICS_ENABLED=false
(system).ADR-076·Guide iPhone·Technical doc
Single: steps (summary, daily breakdown, baseline delta), heart rate (summary, baseline delta), cross-kind (overview, change detection). One agent ↔ one domain pattern, mirroringhealth_agent
with 7 hand-crafted toolsemail_agent
/event_agent
.: aggregation tools accept ISO 8601 bounds exactly liketime_min
/time_max
windowed queriescalendar_tools.search_events_tool
. The QueryAnalyzer resolves "this week" / "last month" into concrete date ranges, and the planner splits them across the two parameters.Inlined figures in the LLM message: all factual data (totals, averages, per-day values) ship in theUnifiedToolOutput.message
so the Response LLM surfaces them without reaching intostructured_data
(pattern fromweather_tools
).Extensible registry(HEALTH_KINDS
): adding sleep / SpO2 / calories = one entry inkinds.py
— bounds, merge strategy, aggregation method, baseline kind. Service helpers iterate the registry so cross-kind logic stays generic.Baseline & variation detection: rolling 28-day median withbootstrap
→rolling
mode switch after 7 days of data, tunable thresholds (HEALTH_METRICS_VARIATION_*
env vars).Heartbeat / Memory / Journal integration:health_signals
source injected for proactive context;context_biometric
JSONB persists deltas and trends in memories (never raw values) when emotional weight crosses a threshold.Per-user opt-in: singlehealth_metrics_agents_enabled
toggle governs the four integrations (tool access, Heartbeat, memory extraction, journal injection).PATCH /auth/me/health-metrics-agents-preference
.
Sandboxed iframes via a CSP airlock(ADR-098): third-party widgets boot through a same-origin shell (public/widget-frame.html
) served with its own permissive CSP, so external-CDN widgets (Excalidraw, …) work while the main app keeps a strict policy. Isolation is the iframesandbox
(opaque origin, no parent cookies/DOM), not the CSP; the shell is hardened by anti-abuse locks +frame-ancestors 'self'
JSON-RPC Bridge: Bidirectional communication between iframe app and chat via PostMessage JSON-RPC 2.0** Excalidraw Iterative Builder**: Intent-based diagram generation via dedicated LLM calls (shapes + arrows) with cheat sheet injection for format accuracy. Runs under a dedicated MCP-step timeout family (300 s floor / 600 s ceiling, ADR-100) so complex diagrams are not cut off mid-generation: MCP servers exposing aread_me
conventionread_me
tool have their content auto-injected into the planner promptAuto-generated descriptions: LLM analysis of discovered tools for domain description optimized for routing** App-only tools**: Tools withvisibility: ["app"]
filtered from the LLM catalogue (iframe only)
LIA is fully translated in 6 languages: English, French, German, Spanish, Italian, and Chinese.
Complete UI coverage: All interfaces, dialogs, notifications, error messages, FAQ, and landing page** HITL localized**: Human-in-the-Loop approval prompts adapted per language** Proactive notifications**: Heartbeat and reminders delivered in the user's language** Telegram**: Inline keyboards and messages localized** Skills**: Auto-translated descriptions in all 6 languages** react-i18next**: Namespace-based translations withlocales/{lang}/translation.json
Animated hero chat demo: three rotating scenarios mirroring the real display modes — HITL draft approval, rich HTML weather card + proactive cross-domain initiative, multi-agent Markdown reply — with per-mode title-bar chipsProof band: verifiable engineering numbers (agents, tools, providers, tests, ADRs, releases, audit score) sourced from the codebase (LANDING_STATS
documents each origin)Two-mode diagram: faithful LangGraph topology — router fork, five numbered pipeline steps (human approval highlighted), ReAct reason→act→observe loop, streaming convergence(6 languages): how LIA is built — method, trade-offs, operations, measured audit profile — on the /why–/how guide pattern/story
field reportSEO & OpenGraph: dynamically generated OG image, per-locale hreflang, JsonLd (WebSite, Organization, SoftwareApplication, breadcrumbs),llms.txt
for AI crawlersPublic-route guard: the 401 handler's public-page list is pinned by a filesystem-completeness test — a new public page missing from the list fails CI instead of ejecting anonymous visitors to /loginAuthenticated redirect: automatic redirect to dashboard if already logged in
LIA includes a full-featured administration interface — giving operators complete control and real-time visibility over the system without touching configuration files or the database.
A web-based administration panel covering every operational aspect:
| Section | Capabilities |
|---|---|
| LLM Configuration | |
| Model selection per node, provider parameters, temperature/token limits, prompt versions | |
| RAG Knowledge Spaces | |
| Manage document spaces, embedding configuration, user reindex operations, system knowledge spaces (FAQ staleness, reindex) | |
| Personalities | |
| Create and manage assistant personalities (tone, language, behavior rules) | |
| User Management | |
| User accounts, roles, permissions, connector status overview | |
| Connector Management | |
| Google/Apple/Microsoft OAuth status, token health, per-user provider activation | |
| Skills Management | |
| Enable/disable skills, edit descriptions, translate in 6 languages, delete | |
| MCP Servers | |
| Admin-level MCP server configuration, tool discovery, domain descriptions | |
| LLM Pricing | |
| CRUD for the full LLM catalogue — provider, 8 capability flags (max input/output tokens, tools, structured output, strict mode, streaming, vision, reasoning) and pricing (input/output/cache tokens) per model. Source of truth for the LangChain factory and the agent constraints. Live cross-worker invalidation, no redeploy | |
| Image Generation Pricing | |
| CRUD for image models — provider, quality, size and pricing. Drives the user preferences dropdowns directly | |
| Google API Pricing | |
| Per-endpoint pricing configuration for Google Maps Platform services | |
| Voice Settings | |
TTS catalogue management (Edge / OpenAI / ElevenLabs) via Configuration LLM (voice_tts type), per-provider tuning, voice picker (live ElevenLabs voices) |
|
| Broadcasting | |
| Send system-wide notifications to all users or targeted groups | |
| Debug Settings | |
| Toggle debug panel visibility, configure diagnostic verbosity per user | |
| Usage Limits | |
| Per-user token/message/cost quotas (period + global), real-time gauges, manual block/unblock, WebSocket live updates | |
| Consumption Export | |
| CSV export of token usage, Google API usage, and aggregated consumption per user/period |
A 24-section debug panel embedded in the chat interface, organized into 6 logical groups with always-visible sections (empty sections show "N/A" instead of disappearing):
| Group | Sections |
|---|---|
| Request Analysis | |
| Intent classification, Domain detection, Routing decision, Query transformations | |
| Planning & Execution | |
| Planner output, Tool selection, Context resolution, Token budget, Execution timeline, ForEach analysis, Execution waves | |
| Intelligent Mechanisms | |
| Cache hits, pattern learning, semantic expansion, Skills activation | |
| Context Injection | |
| Memory injection (scores), RAG injection (scores), Knowledge enrichment (Brave), Journal injection (per-entry scores, budget) | |
| Background Extraction | |
| Memory detection (create/update/delete), Journal extraction, Interest profile | |
| LLM & API Pipeline | |
| Request lifecycle (timing breakdown per node), LLM Pipeline (chronological reconciliation), LLM call details (model, tokens, latency, cost), Google API calls |
The debug panel is designed for
developers and operatorsto diagnose issues, optimize prompts, and understand the agent's decision-making process in real time — without needing external tools or log access.
| Software | Version | Required |
|---|---|---|
| Python | 3.12+ | Yes |
| Node.js | 24 LTS | Yes |
| Docker | 24+ | Yes |
| pnpm | 10+ | Yes |
All commands are defined in Taskfile.yml
. Quick start: task setup
then task dev
.
git clone https://github.com/jgouviergmail/LIA-Assistant.git
cd LIA-Assistant
cp .env.example .env # Edit with your API keys
task setup
task dev
Manual setup (without Task)
docker compose up -d postgres redis prometheus grafana
cd apps/api
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install --require-hashes -r requirements.lock.txt # compiled lockfile (reproducible)
cp ../../.env.example .env # Configure your API keys
alembic upgrade head
cd ../web
pnpm install
cd apps/api && uvicorn src.main:app --reload --port 8000
cd apps/web && pnpm dev
| Service | URL | Credentials |
|---|---|---|
| Frontend | ||
http://localhost:8000/docshttp://localhost:3001http://localhost:9090
DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/lia
REDIS_URL=redis://localhost:6379/0
SECRET_KEY=change-me-in-production-use-openssl-rand-base64-32
FERNET_KEY=your-fernet-key-here
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
MCP_ENABLED=false # Admin MCP servers
MCP_USER_ENABLED=false # Per-user MCP (requires MCP_ENABLED)
CHANNELS_ENABLED=false # Multi-channel messaging (Telegram)
HEARTBEAT_ENABLED=false # Autonomous proactive notifications
SCHEDULED_ACTIONS_ENABLED=false # Recurring scheduled actions
SUB_AGENTS_ENABLED=false # Persistent specialized sub-agents
SKILLS_ENABLED=false # Skills system (agentskills.io standard)
RAG_SPACES_ENABLED=true # RAG Knowledge Spaces (document upload & retrieval)
FCM_NOTIFICATIONS_ENABLED=false # Firebase push notifications
Production targets include Raspberry Pi (ARM64) via multi-arch Docker builds (linux/amd64,linux/arm64
).
┌─────────────────────────────────────────────────────────────────────────┐
│ FRONTEND (Next.js 16 + React 19) │
│ Chat UI • Settings • i18n (6 languages) • SSE Streaming • Voice Mode │
└─────────────────────────────┬───────────────────────────────────────────┘
│ HTTP-only cookies (session_id, 24h TTL)
┌─────────────────────────────┴───────────────────────────────────────────┐
│ BACKEND (FastAPI + LangGraph 1.x) │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ LangGraph Multi-Agent Orchestration │ │
│ │ │ │
│ │ Router → QueryAnalyzer → Planner → ApprovalGate → Orchestrator │ │
│ │ ↓ ↓ │ │
│ │ ┌─────────────────────────────────────────────────────────────┐ │ │
│ │ │ Contacts │ Emails │ Calendar │ Drive │ Tasks │ Reminders │ │ │
│ │ │ Places │ Routes │ Weather │ Wikipedia │ Perplexity │ │ │
│ │ │ Brave │ Web Search │ Web Fetch │ Browser │ Context │ Query│ │ │
│ │ └─────────────────────────────────────────────────────────────┘ │ │
│ │ ↓ │ │
│ │ MCP Tools (per-user external servers) │ │
│ │ ↓ │ │
│ │ Response Node (synthesis) │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐│
│ │ Domain Services: Auth, Users, Connectors, RAG, Voice, Skills... ││
│ └─────────────────────────────────────────────────────────────────────┘│
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐│
│ │ Infrastructure: Redis (cache) • PostgreSQL (checkpoints) • ││
│ │ MCP Client Pool • Prometheus (metrics) • Langfuse (traces) ││
│ └─────────────────────────────────────────────────────────────────────┘│
└──────────────────────────────────────────────────────────────────────────┘
LIA offers two execution strategies, switchable per user via a toggle in the chat header:
Pipeline mode (default) — A feat of engineering that delivers the same power as ReAct with 4–8× fewer tokens:
- A smart
Planner decomposes the request into an optimized execution plan (DSL) - A
Semantic Validator checks plan coherence (cardinality, scope, dependencies) - An
Approval Gate handles HITL for mutations - A
Task Orchestrator executes tools in parallel waves via
asyncio.gather()
Bayesian learning optimizes planning patterns over time
ReAct mode (⚡) — The LLM reasons iteratively, calling tools one by one and adapting to each result. More autonomous but higher token cost. Ideal for exploratory, research, or ambiguous queries.
graph TD
A[User Message] --> B[Router Node]
B -->|conversation| C[Response Node]
B -->|pipeline mode| D[Planner Node]
B -->|react mode| R1[ReAct Setup]
D --> E[Semantic Validator]
E --> F{Approval Gate}
F -->|approved| G[Task Orchestrator]
F -->|rejected| C
G --> H[Domain Agents + Tools]
H --> G
G --> C
R1 --> R2[ReAct Call Model]
R2 -->|tool_calls| R3[ReAct Execute Tools]
R2 -->|done| R4[ReAct Finalize]
R3 --> R2
R4 --> C
C --> J[SSE Stream]
apps/api/src/
├── core/ # Modular configuration (9 modules)
│ ├── config/ # Settings per domain
│ ├── constants.py # Global constants
│ └── bootstrap.py # Initialization functions
├── domains/ # Bounded Contexts (DDD)
│ ├── agents/ # LangGraph nodes, services, tools
│ │ ├── nodes/ # Graph nodes (router, planner, react ×4, response...)
│ │ ├── services/ # Smart services, HITL
│ │ ├── tools/ # Domain-specific tools
│ │ └── orchestration/ # ExecutionPlan, parallel executor
│ ├── auth/ # JWT, sessions, OAuth
│ ├── connectors/ # Google + Apple + Microsoft clients, provider resolver
│ ├── conversations/ # Conversation CRUD & history
│ ├── google_api/ # Google API pricing & usage tracking
│ ├── rag_spaces/ # RAG Knowledge Spaces (upload, embed, retrieve, system FAQ)
│ ├── user_mcp/ # Per-user MCP servers (CRUD, OAuth, domain routing)
│ ├── voice/ # TTS factory, STT, Wake Word
│ ├── skills/ # Skills system (agentskills.io standard)
│ ├── sub_agents/ # Persistent specialized sub-agents (F6)
│ ├── interests/ # Interest Learning System
│ ├── heartbeat/ # Autonomous Heartbeat (Proactive Notifications)
│ ├── channels/ # Multi-channel messaging (Telegram)
│ ├── reminders/ # Reminder & notification scheduling
│ ├── scheduled_actions/ # Recurring scheduled actions
│ ├── journals/ # Personal Journals (introspective notebooks)
│ ├── health_metrics/ # iPhone Shortcuts health ingestion + charts
│ └── users/ # User management
└── infrastructure/ # Cross-cutting concerns
├── cache/ # Redis sessions, LLM cache
├── llm/ # Factory, providers, embeddings
├── mcp/ # MCP client pool, auth, security, tool adapters
├── browser/ # Playwright session pool, CDP accessibility
├── rate_limiting/ # Distributed rate limiter
└── observability/ # Metrics, logging, tracing
Tool System (5-layer architecture) — Tools are built in five composable layers: ConnectorTool[ClientType]
(generic base with OAuth auto-refresh), @connector_tool
(meta-decorator composing metrics + rate limiting + context save), Formatters (domain-specific result normalization), ToolManifest
- Builder (declarative declaration with semantic keywords), and Catalogue (dynamic introspection). Per-tool boilerplate reduced from ~150 to ~8 lines (94% reduction). Category-based rate limits: Read (20/min), Write (5/min), Expensive (2/5 min).
Domain Taxonomy — Each domain is a declarative DomainConfig
(agents, result_key
, related_domains
, priority, routability). The DOMAIN_REGISTRY
is the single source of truth consumed by SmartCatalogue (filtering), semantic expansion (adjacent domains), and the Initiative phase (structural pre-filter).
Data Registry — An InMemoryStore
decouples tool results from message history. Results survive per-node message windowing (5/10/20 turns) via @auto_save_context
, and cross-step references ($steps.X.field
) resolve against the registry — this is what makes aggressive windowing viable without losing tool output context.
Semantic Validator — Before HITL approval, a dedicated LLM (distinct from the planner) inspects plans against 14 issue types across four categories: Critical (hallucinated capability, ghost dependency), Semantic (cardinality mismatch, scope overflow), Safety (dangerous ambiguity), and FOR_EACH-specific validations.
Adaptive Re-Planner — On execution failure, a rule-based analyser classifies the failure pattern and selects a recovery strategy. In Panic Mode, the SmartCatalogue expands to all tools for one retry, solving cases where domain filtering was too aggressive.
Connector Abstraction — Python protocols enable transparent switching between Google, Apple, and Microsoft providers. Normalizers convert provider-specific responses into unified domain models. The ProviderResolver
guarantees only one provider per functional category (email, calendar, contacts, tasks).
Error Architecture — All tools return ToolResponse
/ToolErrorModel
with a ToolErrorCode
enum (18+ types) and a recoverability
flag. API-side centralized exception raisers replace raw HTTPException everywhere.
Feature Flags — Every optional subsystem is controlled by a {FEATURE}_ENABLED
flag, checked at startup, route wiring, and node entry (instant short-circuit).
Full technical details:
[How does LIA work?]— 25-section architecture guide
| Technology | Version | Role |
|---|---|---|
| Python | 3.12+ | Primary runtime |
| FastAPI | 0.136.3 | REST API + SSE framework |
| LangGraph | 1.2.4 | Multi-agent orchestration |
| LangChain | 1.3.9 | LLM abstraction + tools |
| SQLAlchemy | 2.0.50 | Async ORM |
| Alembic | 1.18.4 | Database migrations |
| PostgreSQL | 16 + pgvector | Database + vector search |
| Redis | 7.4.0 | Cache, sessions, rate limiting |
| Pydantic | 2.13.4 | Validation + serialization |
| structlog | latest | Structured JSON logging |
| openai | 2.x | LLM provider |
| Edge TTS | 7.2+ | Voice synthesis (free) |
| mcp | 1.9+ | Model Context Protocol SDK (Streamable HTTP) |
| Docker | 24+ | Containerization (multi-arch amd64/arm64) |
| Technology | Version | Role |
|---|---|---|
| Node.js | 24 LTS | JavaScript runtime |
| Next.js | 16.2.10 | React framework |
| React | 19.2.7 | UI library |
| TypeScript | 6.0.2 | Type safety |
| TailwindCSS | 4.3.2 | Styling |
| TanStack Query | 5.101 | Server state management |
| react-i18next | 17.0.8 | i18n (6 languages) |
| Radix UI | latest | Accessible UI primitives |
Responsive Design: Fully optimized for desktop, tablet, and smartphone. Adaptive layouts, touch-friendly interactions, and mobile-first components ensure a seamless experience on any device.
| Provider | Models | Use Case |
|---|---|---|
| OpenAI | GPT-5.4, GPT-5.4-mini, GPT-5.2, GPT-5.1, GPT-5, GPT-5-mini/nano, GPT-4.1, GPT-4.1-mini/nano, GPT-4o, o1, o3-mini | Primary (prompt caching, reasoning) |
| Anthropic | Claude Opus 4.6/4.5, Claude Sonnet 4.6, Claude Haiku 4.5 | Alternative (extended thinking) |
| Gemini 3.1/3/2.5 Pro, Gemini 3/2.5/2.0 Flash | Multimodal | |
| DeepSeek | deepseek-v4-flash, deepseek-v4-pro (V4 family — thinking-mode toggle, v1.19.1+), deepseek-chat (V3, legacy), deepseek-reasoner (R1, legacy) | |
| Cost-effective reasoning. V4 supports tools + structured output via JSON-mode fallback when thinking is on. | ||
| Perplexity | sonar-small/large-128k-online | Web-augmented responses. Base URL configurable via PERPLEXITY_BASE_URL env var (v1.19.1+). |
| Qwen | qwen3-max, qwen3.5-plus, qwen3.5-flash | Thinking + tools + vision (Alibaba Cloud DashScope). Base URL configurable via QWEN_BASE_URL (regional US/CN swap, v1.19.1+). |
| Ollama | Any local model (dynamic discovery) | Zero API cost, self-hosted. Base URL configurable via OLLAMA_BASE_URL . |
| Technology | Role |
|---|---|
| Prometheus | 419 metrics |
| Grafana | 25 dashboards |
| Loki | Aggregated logs |
| Tempo | Distributed tracing |
| Langfuse | LLM observability |
| structlog | Structured JSON logs |
| Document | Description |
|---|---|
ARCHITECTURE.mdINDEX.md| Domain | Documents | |---|---| Agents & LLM | |
HITLHITL•PLAN_HITL_STREAMING_VALIDATIONVoiceVOICE•VOICE_MODEMemoryLONG_TERM_MEMORY•MEMORY_RESOLUTIONMCPMCP_INTEGRATION•GUIDE_MCP_INTEGRATIONHeartbeatHEARTBEAT_AUTONOME•GUIDE_HEARTBEATChannelsCHANNELS_INTEGRATION•GUIDE_TELEGRAMScheduled ActionsSCHEDULED_ACTIONS•GUIDE_SCHEDULED_ACTIONSSkillsSKILLS_INTEGRATION** Sub-Agents**SUB_AGENTS** RAG Spaces**GUIDE_RAG_SPACES•ADR-055•ADR-058Browser ControlBROWSER_CONTROL•ADR-059Personal JournalsJOURNALS•ADR-057LLM ProvidersLLM_PROVIDERS** CI/CD**CI_CD** Security**SECURITY•OAUTH•RATE_LIMITINGObservabilityOBSERVABILITY_AGENTS•METRICS_REFERENCECost TrackingLLM_PRICING_MANAGEMENT•GOOGLE_API_TRACKING| Guide | Description | |---|---| |
GUIDE_AGENT_CREATIONGUIDE_TOOL_CREATIONGUIDE_TESTINGGUIDE_DEBUGGING100+ ADRs (numbered up to ADR-108) documenting major architectural decisions:
ADR-007: Service Layer Pattern for Node ComplexityADR-048: Semantic Tool RouterADR-051: Reminder & Notification SystemView all ADRs
cd apps/api
pytest tests/unit -v
pytest tests/integration -v
pytest tests/agents -v
pytest --cov=src --cov-report=html -v
| Metric | Value |
|---|---|
| Total backend tests | ~11,970 (pytest collected, 670 test files) |
| Backend breakdown | unit fast ~10,150 · agents ~970 · integration ~580 (zero skips) |
| Frontend tests (vitest) | 1,222 (+ 17 hermetic Playwright E2E incl. axe/dark/zoom) |
| Coverage target | 45% backend (ratchet) · frontend thresholds locked per category |
| CI Workflows | 3 (CI, Security, Release) |
| Technical audit | 8.3/10 across 24 normalized areas — |
LIA uses a two-layer quality gate: a local pre-commit hook (fast, on staged files only) and a GitHub Actions CI pipeline (comprehensive, on every push/PR to main
).
Pre-commit (local) GitHub Actions CI
=================== ==================
.bak files check Lint Backend (Ruff + Black + MyPy)
Secrets grep Lint Frontend (ESLint + TypeScript)
Ruff + Black + MyPy Fast unit tests + coverage (45%)
Fast unit tests Integration tests (PostgreSQL + Redis)
Critical pattern detection Agents suite
i18n keys sync Code Hygiene (i18n, Alembic, lockfiles, patterns)
Alembic migration conflicts Docker build smoke test
.env.example completeness Secret scan (Gitleaks)
ESLint + TypeScript check ──────────────────────
Security workflow (weekly)
CodeQL (Python + JS)
Dependency audit (pip-audit + pnpm audit)
Trivy filesystem scan
SBOM generation
| Practice | Implementation |
|---|---|
| SHA-pinned Actions | |
| All GitHub Actions pinned by commit SHA (supply-chain security) | |
| Reproducible builds | |
| Universal Python lockfiles (linux/amd64 + arm64 + Windows), SHA256 hash-verified installs everywhere; CI guard fails manifest edits without lock regeneration ( | |
Least privilegepermissions: contents: read
on CI workflowBranch protectionDependabotPre-commit / CI alignment****Coverage threshold| Workflow | Trigger | Jobs |
|---|---|---|
CI (ci.yml ) |
Push to main , PR |
8 jobs: lint, unit tests, integration tests, code hygiene, docker build, secret scan |
Security (security.yml ) |
PR, weekly schedule, manual | CodeQL, dependency audit, Trivy, SBOM |
Release (release.yml ) |
Tag v* |
Docker multi-arch build + push (ghcr.io), GitHub Release |
Full details:
[CI/CD Documentation]
| Metric | Value | SLO |
|---|---|---|
| API Latency | 450ms | < 500ms |
| First SSE event (request acknowledged) | 380ms | < 500ms |
| Router Latency | 800ms | < 2s |
| Planner Latency | 2.5s | < 5s |
| Gemini Embedding | ~100-200ms | < 300ms |
| Token Reduction (Windowing) | 93% | > 80% |
| Context Compaction Savings | ~60% per compaction | — |
These figures measure the infrastructure. The full perceived response time depends on the LLM call cascade (seconds to tens of seconds depending on request complexity and hardware) — this is the main optimization programme in progress, measured in production. The
[July 2026 technical audit]scores Performance 7.5/10: instrumentation and caching are in place, but no sustained load campaign has been executed yet.
Message Windowing: 5/10/20 turns depending on node** Context Compaction**: LLM summarization of old messages (dynamic threshold from response model context window, configurable viaCOMPACTION_*
settings)Prompt Caching: OpenAI/Anthropic (90% discount)** Gemini Embeddings**: gemini-embedding-001 with asymmetric task types (multilingual)** Parallel Execution**: asyncio.gather for independent domains** Redis O(1): Optimized operations (vs O(N) SCAN) Connection Pooling**: httpx persistent connections
| Standard | Status |
|---|---|
| GDPR | PII filtering, data minimization |
| OWASP Top 10 | XSS, SQL injection, CSRF protection |
| Prompt Injection | External content wrapping (<external_content> safety markers) |
| OAuth 2.1 | Mandatory PKCE |
| Supply chain | Hash-verified universal lockfiles, pip-audit on the full transitive tree, SBOM per release |
DO NOT create a GitHub Issue for security vulnerabilities.
Send an email to ** liamyassistant@gmail.com** with:
- Description of the vulnerability
- Steps to reproduce
- Potential impact
We respond within 48 hours.
We welcome all contributions! See our Contributing Guide to get started.
git clone https://github.com/YOUR-USERNAME/LIA-Assistant.git
cd LIA-Assistant
git checkout -b feature/my-feature
task setup
task test:backend:unit:fast
git commit -m "feat(agents): add weather forecast agent"
git push origin feature/my-feature
- Bug fixes
- New features
- Documentation
- Tests
- i18n translations (6 supported languages)
- Performance optimizations
Python: Black + Ruff + MyPy (strict)** TypeScript**: ESLint + Prettier** Commits**:Conventional Commits** Coverage**: >= 45% enforced in CI (ratchet +2 per release, never lowered)** Pre-commit hook**: Installed viatask setup
— runs linters + tests on staged filesCI: All PRs must pass 7 status checks before merge (seeCI/CD)
| Channel | Usage |
|---|---|
GitHub Discussionsliamyassistant@gmail.comThis project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).
See LICENSE for details.
A commercial license is also available for organizations that cannot comply with AGPL-3.0 terms. Contact liamyassistant@gmail.com for details.
This project builds on excellent open source technologies:
Backend & Infrastructure
Python- Primary runtimeFastAPI- Modern async web frameworkLangGraph- Multi-agent orchestrationLangChain- LLM abstraction & toolsSQLAlchemy- Async ORMPydantic- Data validation & settingsAlembic- Database migrationsPostgreSQL+pgvector- Database & vector searchRedis- Cache, sessions, rate limitingGoogle Gemini Embeddings- gemini-embedding-001 for multilingual semantic searchEdge TTS- Free neural voice synthesisstructlog- Structured JSON loggingDocker- Containerization & multi-arch builds
Frontend
Node.js- JavaScript runtimeNext.js- React frameworkReact- UI libraryTypeScript- Type safetyTailwindCSS- Utility-first stylingRadix UI- Accessible UI primitivesTanStack Query- Server state managementreact-i18next- Internationalization (6 languages)
Observability
Prometheus- Metrics & alertingGrafana- Dashboards & visualizationLoki- Log aggregationTempo- Distributed tracingLangfuse- LLM observability & prompt management
LIA — Next-Generation Intelligent Conversational Assistant
Built with ❤️ using Python, Node.js, FastAPI, LangGraph, and Next.js