开源个人助理 LIA 发布 3.0.0，支持对话式配置与 ReAct 结果校验

Your day. LIA keeps up. You decide.
A personal assistant that brings your context together, helps you follow through, and prepares actions for review.
Designed in France · Open source · Self-hostable · Six-language interface

Prepare a conversation. Listen to your day. Keep track of your commitments.

Features • Admin & Monitoring • Quick Start • Architecture • Documentation • Contributing • Changelog

Version 3.0.0 — Your requests, their context, a result you can verify. Manage supported LIA settings and objects through conversation, with explicit confirmation for sensitive operations. ReAct checks requested outcomes against structured results and reuses eligible fresh reads within a turn. Native companions gain reviewed body volume, and the editable product film explains the main workflows. Experimental speaking-avatar provider and physical Android/iOS qualification remains separate.

Table of Contents

• What is LIA?
• Try LIA Online
• Product presentation
• Screenshots
• Features
• Administration & Monitoring
• Built by an AI, Directed by a Human
• Quick Start
• Architecture
• Technologies
• Quality: Tests, CI/CD, Security
• Documentation
• Contributing
• Support
• License
• Acknowledgments

What is LIA?

LIA is an open-source personal AI assistant in a web application you can host yourself. It connects the information you make available — emails, calendar, documents, preferences and commitments — to help you prepare conversations, organize your day and follow through.

Its strength is the continuity between those activities. Memory, knowledge spaces, meeting records and Relations, its personal relationship view, make relevant context available for the next supported request. A preference you correct, a document you keep or a commitment you record can become useful again. Each feature contributes through its own sources, permissions and settings.

LIA also helps between conversations: a daily briefing, a personal Radio, reminders, routines and proactive suggestions. You choose the sources and enabled features, and the time windows and channels for proactive help. Chat, rich cards, voice and Live sessions keep this assistance accessible in the same application.

You can inspect sources, correct remembered information and review prepared drafts. Actions covered by approval flows ask for your decision before execution. Registers expose recorded consultations, action attempts and outcomes; usage and budgets are visible to users and operators.

Start with something that would help you

These examples use the services and permissions enabled on your instance. Generated conclusions and documents remain yours to review.

What LIA brings together

Cloud models and compatible local models served through native Ollama can be configured for supported processing roles. Model capabilities, host resources and enabled external services determine the available features and where information is processed. Hosting and provider services may incur costs.

A foundation for an internal company assistant

Preparing meetings, retrieving business knowledge and following commitments can also help colleagues. LIA's multi-user web application, connectors, MCP, APIs and observability provide a foundation to customize and integrate into your organization.

Define the deployment's identity, permissions, business sources, usage rules, integrations and hosting. The architecture, documentation and self-hosting guide help scope that work.

Try LIA Online

Explore LIA and its real interface or try the public demonstration.

The public demonstration uses fictional scenarios. When the guided showroom is enabled, it illustrates requests, context, results and approval controls using the application's rendering components, without contacting a real model, account or external service. Source links let you inspect the mechanisms behind that showroom; a live demonstrator is offered when the instance publishes one.

Closed beta — account access and activation are granted at the administrator's discretion. To request an invitation, write to liamyassistant@gmail.com.

To run your own LIA, start with Quick Start or the production installation guide.

Product presentation

Watch or download the complete film. The French presentation follows concrete uses, contextual native avatars, display modes, reminders, Relations, planned actions, administration and the installable mobile web application. Interfaces follow the product's UI with fictional demonstration data. The landing's blue Presentation button opens the full film with sound and controls in an exclusive fullscreen player.

The editable construction, production and update procedure and decision record preserve the scenario, native-view sources, feature focuses and soundtrack provenance for future product updates. Release assets include a checked editable source archive. The video is a product demonstration, not a recorded provider session.

Screenshots

The application views below show the real interface in English with fictional demonstration data. They illustrate workflows and controls; no model, connected account or external action was exercised in these captures. The Radio player used a local silent audio fixture.

Your personal hub — daily summary, calendar, emails, tasks and reminders in one place, with activity and usage at a glance.

This home dashboard capture is retained from the earlier public screenshot campaign, documented in the capture workflow.

Open any image for its full resolution. For the workflow captures below, the application manifest records the capture provenance, native BIP masculine selection and interactions; the capture runner reproduces this campaign.

Prepare a conversation with the relevant sources and open questions in view.

Relations — pick up the conversation with recent exchanges and open commitments beside you.

Personal Radio — your day and selected news, with the programme and sources in the actual player.

Meetings, knowledge, memory and actions you can review

Meetings — review decisions and assigned action items, then edit or export the report.

Review a prepared message through the application’s approval controls.

Knowledge spaces — documents and connected sources you can manage.

Review and correct what LIA remembers.

A useful mini-app inside the conversation — the actual unit-converter widget.

Administration — account budgets and the instance ceiling, with visible usage gauges.

The Administration & Monitoring section below includes the three Grafana views supplied by the project.

Features

Every capability below is documented in an architecture decision record (ADR) or a technical document — the links lead there.

Talk to it

A chat that streams

• Answers arrive over SSE with rich HTML cards, interactive widgets and a per-message cost badge.
• A data card shows everything the source supplied and never invents a missing value — an e-mail's body, every organisation of a contact, conference join points, subtasks, a place's photos (full-screen gallery), reviews and opening hours, a route's alternatives, weather slots, generated-document previews — the detail behind native disclosures; opening one calls nothing. The model reads a versioned semantic view of the answer, never the card's HTML (ADR-332, HTML_CARDS).
• Reply, forward, move an e-mail to the trash or adjust a reminder from its card: the request is prepared in the composer, and the server re-checks the original message, source and account grant. E-mail deletion still passes through approval before changing its original mailbox. A route opens as an interactive Google map whose estimated cost is announced first and every construction counted (ADR-332).
• MCP cards name the server's public origin and the called method above an accessible response disclosure; opening it reveals the received result without another call. Weather icons follow the provider's condition codes and day/night information, across current, daily and hourly forecasts.
• In the rich HTML mode every data-bearing answer is a composed page — a lead sentence, one section per facet in the component that fits it, a closing callout — laid out on conversational turns too unless a voice is reading them (ADR-177).
• Images and PDFs can be attached (vision analysis, text extraction, strict per-user isolation).
• Long conversations are compacted by an LLM summary that preserves identifiers, the history scrolls back page by page without limit, and each answer is shared — to the device's sheet, or to a connection through an ordinary confirmed message — or downloaded as a dated Markdown file in one click. A formatted answer keeps its headings, lists, tables, links and code in that file, its cards summed up as a heading and a few bullets; copying stays plain text (ADR-177).
• The text size is a per-account preference from 14 to 20 px: only the text scales, panels, spacing and icons keep their dimensions.

One conversation across devices and channels

• Once a message is committed, the open chat learns of it and merges the new history without replacing older pages, moving the reader or interrupting an action. Other tabs, calls, routines and external channels become visible without a reload.
• A reconnected tab catches up after an interruption (ADR-320).

Voice, both ways

• Push-to-talk, or the wake word "Dis LIA" — a small trained model run by ONNX Runtime in a browser worker, every file checked against its SHA-256, so no audio leaves the device for detection. "Stop" cuts LIA's voice while it reads an answer. French only for now, in beta; the other interface languages keep tap-to-speak (ADR-329, WAKE_WORD_TRAINING).
• Offline Whisper transcription in the user's own language.
• Spoken answers from a catalogue-driven TTS (Edge, free; OpenAI; ElevenLabs), streamed sentence by sentence. Playback can begin before the complete answer is available; startup latency depends on the model, provider and connection (VOICE, ADR-081, ADR-082).
• ElevenLabs synthesis shares an administrator-set concurrency ceiling across API workers and speech surfaces; the browser plays queued audio in sequence, even when synthesis completes out of order.

A personal speaking avatar, experimental

• Connect your own Simli account, choose a face and explicitly authorize its use. The operator must first enable the optional capability; it is off by default.
• A floating window with three sizes follows existing voice comments and Live conversations, with touch/pointer dragging and keyboard movement. The avatar and local player share one audible destination.
• The window keeps its explicit stop control even when the chat encounters an error, and reports confirmed or pending closure. Mobile keyboard, rotation and zoom adjustments preserve the chosen placement.
• The connection stays open while the voice mode is active; silence can consume your personal Simli credits. Live standby closes it, and waking opens a new connection. Radio is outside this integration.
• Provider lip motion, long silence, renewal and physical Android/iOS audio remain subject to qualification (SPEAKING_AVATAR, proposed ADR-334).

Live, voice to voice

• A real-time session on a live model the person connects with their own key (Gemini Live over a WebSocket, GPT-Live over WebRTC, or an ElevenLabs agent whose voice stays on its portal).
• The Live provider connection carries audio directly between the browser and provider. With the optional avatar enabled, LIA's spoken output also passes through the API-controlled Simli relay; its provider token stays encrypted server-side.
• In supported Live configurations, the voice model can delegate a data request or action to the chat engine. The delegated turn uses the graph’s approvals, registers and quotas and appears in the thread. Concurrent speech, interruption and delegation behavior depend on the provider, model and mode.
• A provider declares its wire and the seam never branches on its name.
• A direct session holds the read-only tools itself and acts on nothing.
• A silence puts the session on standby instead of ending it: the provider connection closes and nothing is billed until the phrase or a tap wakes it into a new connection; only the person ends a session (ADR-329).
• The provider's own usage is folded into an indicative meter and shown, never recorded — the vendor's bill read once at the end where it has one (ADR-299, ADR-300, LIVE_MODE).

A personal radio, on demand

• A deterministic programme grid blends the listener's day with news from identified sources.
• Models write and voice the segments, while verification decides what may air. The listener chooses subjects, sources, voices and verification, sees sources and live cost, and ends the session with a timer. Production runs only while someone listens.
• An administrator controls the capability and the guided self-host installer asks before enabling it (ADR-324, RADIO).
• The radio settings group programme, sources, verification, voices and spending so a listener can see what will be used before starting.
• Editorial selection excludes advertisements, sponsorships and purchase pitches while retaining genuine news, scientific reporting, invoices, reservations and appointments. Raw PCM and µ-law speech are wrapped with their actual format before mixing.

An expressive companion

The complete native catalogue uses original designs and contextual expressions. Reviewed offline artwork supplies bounded body relief, while the shared rig owns head pose, eyes, brows and mouth. Reduced motion and unavailable graphics retain their native fallback. See the volume guide for projection and performance limits.

• Psyche temperament, actual tool execution and the delivered answer's tone share one animation rig, including the shaded Smiley. Eyes lead a head with depth and weight.
• Continuous mouth/brow contours, quiet thought and varied resting scenes keep transitions natural. Speech follows actual audio, and a prepared draft never earns an accomplished-action gesture. Fresh cached weather and the account clock add discreet ambience without a provider or LLM call.
• Reduced motion keeps static contextual poses (ADR-240, ADR-252, ADR-253, ADR-264, ADR-294).

A psyche of its own

• Big Five traits, a mood space, discrete emotions, a relationship stage and curiosity drives shape word choice and rhythm without ever being announced.
• A four-chart dashboard, temperament sliders and two reset scopes in Settings (PSYCHE_ENGINE).

Wherever you are

• Six languages end to end (UI, approvals, notifications, Telegram, skills).
• A bidirectional Telegram channel with OTP linking and localized approval keyboards (GUIDE_TELEGRAM).
• Native Android and iOS shells that load your server, with native push and the sign-in flow Google permits (ADR-246, GUIDE_MOBILE_ANDROID, GUIDE_MOBILE_IOS).
• An offline-capable PWA (ADR-146).

Connect your world

Mail, calendar, contacts, tasks

• Google (OAuth 2.1 + PKCE), Apple iCloud (IMAP/SMTP, CalDAV, CardDAV) and Microsoft 365 (Graph API, personal and business tenants).
• One active provider per category; activating one deactivates its competitor.
• Google and Microsoft each offer one consent to connect or reconnect several services on the same verified account, and the connection alert offers it as soon as two services of one provider have expired. Each service can still be disconnected separately (ADR-302, OAUTH).

E-mail, read whole and clean

• The three providers speak one vocabulary at the client boundary: a text body, never HTML, with quoted history and signature removed, measured on real payloads.
• The assistant chooses how much to read from the question: headers to list, a body paginated by paragraph to read, or a digest per message to reason over many. A small model computes each digest once; it is cached thirty days and counted in your usage. If digest generation fails or is truncated, the original body remains available (ADR-287, EMAIL_FORMATTER).
• An attachment is read too — its text when it has one, the vision slot for a picture or a scan — bounded, paginated and treated as what a stranger sent (ADR-296).

Connected from the first day

• The connectors that ask nothing of the person (Wikipedia, page browsing, Google Places, Weather and Environment) belong to the instance: no per-account row and no entry in « My connectors », always on unless the administrator switches one off for everyone or the instance has no platform key.
• For the weather, a person's own OpenWeatherMap key takes precedence over the instance's default (ADR-307, CONNECTORS_PATTERNS).

Documents, places and weather

• Google Drive folders, sub-folders included, and a Gmail label as knowledge sources, synced incrementally, with the exact number of files stated before a large sync starts (ADR-262, ADR-297).
• Google Maps places, routes and geocoding.
• Weather with change detection.
• A last-known-position cascade so every feature knows where you are, with the age of the fix stated (ADR-219).

Home and body

• Philips Hue lighting by voice (rooms, scenes, local bridge or cloud).
• Daily steps and heart-rate batches pushed from an iPhone Shortcut, idempotently, with baselines, variation detection and charts (ADR-076, ADR-148, GUIDE_IPHONE_SHORTCUTS_HEALTH).

Your own tools (MCP)

• Per-user servers with API key, bearer or OAuth 2.1 authentication (dynamic registration, PKCE), HTTPS-only, SSRF-checked, credentials encrypted.
• Conformant to the protocol's current revision on both halves and reading tool declarations to the letter of JSON Schema 2020-12 (ADR-224, ADR-255).
• MCP Apps rendered as sandboxed widgets behind a CSP airlock (ADR-098).
• An iterative mode where a dedicated agent reads a complex server's docs before calling it (MCP_INTEGRATION).
• A provider's cooldown is shared across workers for that person's server, so another concurrent request cannot restart a wait the service already imposed.

Skills and plugins

• Agentskills.io skills with progressive disclosure, sandboxed scripts and rich outputs (maps, dashboards, calendars, QR codes…), written from a conversation and proposed on a card the person installs in one click (SKILLS_INTEGRATION).
• A public skill library: search skills.sh, read a skill's every file, source, exact version and published audits before installing it at the commit that was read, and update it when its folder moves; a skill from the library, an address or a plugin is third-party — run in an isolated runner, never near a connector, its answer drawn without images or HTML (ADR-327).
• Skills that run their own commands — Python, Node, shell — in a throwaway copy of their folder, from a dedicated sandbox image with no Docker client and no application code; what they write comes back as generated files, and a command reaches only the hosts it declares, through the egress proxy.
• Agent Plugins v1 packages — skills plus streamable-http MCP servers — installed in one step with an exhaustive per-component report (ADR-225).

Act, under your control

Manage LIA through conversation

Ask LIA to inspect or change supported preferences and application objects: reminders, routines, memories, skills and other declared capabilities. Reads and minor reversible settings follow their own authorization policy; creations, deletions and sensitive operations present a reviewable confirmation. File, private-input and connector authorization steps continue through their native browser flows. Commands remain account-scoped, expiring and checked against current authority; administrator capabilities stay reserved to administrators. The application commands guide describes the supported surfaces and secure continuation contract.

Two execution modes, one toggle

• The pipeline builds and validates a plan, applies the required approval gates and executes tools in dependency-aware waves.
• ReAct adapts its next steps to tool results for exploratory or ambiguous requests. Token use and latency depend on the task and configured models.
• Both stream through the same response node (ADR-070, PLANNER).
• A ReAct tool result is projected item by item under a token budget derived from the slot's own window, never cut mid-item, the cut stated to the model and counted (ADR-286).
• The loop binds its tools by relevance — the detected domains' tools, the best-ranked doors of every other family, the top of the turn's global ranking — so no family falls off a blind cap and the schemas stop being most of the prompt, and it reads the same knowledge spaces the pipeline reads (ADR-293).
• A ReAct turn is judged on its result: every fact the loop set out to obtain ends obtained or declared with the rungs tried. A declared gap buys one bounded recovery pass through a node that calls no model (ADR-310).
• Requested outcomes are checked against canonical structured observations, including the value, operation, account and completeness expected. A draft, opaque result or delegated announcement does not prove completion. Independent eligible reads return checkpointed segments; exact fresh reads may be reused within the same turn, with mutation invalidation and bounded budgets (ADR-336, ADR-337).
• Each person picks an exchange rhythm. Frequent binds every tool, moves the turn's context after the question and drops the history by blocks anchored on the turn counter, so the provider's prompt cache is read from one turn to the next. Occasional keeps the relevance selection at a steady cost (ADR-308, ADR-311).

Human-in-the-Loop

• Five interrupting approval levels (clarification, draft critique, destructive confirmation, bulk FOR_EACH confirmation, modifier review) plus plan approval, currently auto-approved because tool-level approval supersedes it (HITL, ADR-106).
• Several independent drafts in one turn are reviewed one per question, with their position stated and nothing executed before the last answer, while a lot you pre-approved as a list keeps its grouped confirmation (ADR-288).
• A draft and its report are described once and drawn per surface — a lia-card in the chat, Markdown on a ticket or an external channel — the report naming to whom and what (ADR-289).
• An e-mail to yourself needs no confirmation, because its recipient is not a parameter — the address your mailbox's provider states, or your verified one through LIA's relay — so a routine can send you its result (ADR-314).

Phone calls on your behalf — and to you

• Through your own ElevenLabs + Twilio connector, calls to third parties require confirmation before dialing. You review the recipient, number and objective; instructions bound the mandate, calendar access exposes free/busy information, and the call is not recorded. The post-call summary and available usage information remain reviewable (ADR-127, TELEPHONY).
• The phone as a channel: LIA calls you on a number you declared and verified by a spoken code, with no confirmation card, the chat's own context and your configured personality on the line.
• The voice agent reads everything the chat reads through the same read-only tools (mails, calendar, tasks, contacts, files, places, weather, memory — one switch per domain, yours) and acts on nothing.
• What you say comes back as your own message, with drafts to confirm in the chat, ten relay verdicts and one bill per call for what LIA spent (ADR-290).
• Since ADR-301 a voice session has a mode, and the policy follows it whatever the line. In Live (the default), each request is a chat turn of yours handled while you speak; a question LIA asks is the answer, and the next request resumes the run that asked. In Live direct, the voice reads and the words are relayed at the end. Phone and browser share one closing; the effective mode is derived and published, and the browser's direct session is relayed like a call (ADR-301).

Documents and images

• CSV, Excel, Word, PowerPoint, PDF, Markdown or text produced by local renderers with each format's native mechanisms (styles, fields, layouts, typed tables, bookmarks).
• Format-specific renderers manage layout, and truncated structured model output is rejected instead of silently producing an incomplete file (ADR-226, ADR-274, ADR-275).
• Image generation and natural-language editing on OpenAI GPT Image or Qwen Image 3.0 — a model family declares its offer, so nothing the configured model cannot serve is priced, offered or selected, the person's preference is resolved to that offer and every image arrives in the chosen format (ADR-305, IMAGE_GENERATION).
• On request, a new image's description is rewritten following the provider's own advice — a quoted text kept word for word, the original sent whenever in doubt, an edit never rewritten (ADR-315).

Keep and send what LIA made

• Generated images, documents and screenshots can be kept without a deadline within published account limits, or released to a fresh normal deadline.
• Their chat cards reflect the current state (ADR-319).
• A file or answer can be sent by e-mail with a subject and optional note: chosen recipients through a connected mailbox, or the account's verified address through LIA's relay, under the selected provider's displayed size limit; typing a recipient suggests the person's contacts by name or phone number and inserts their address (ADR-321).

A browser, a sandbox, delegates

• Browser control with progressive screenshot streaming (ADR-059).
• A short Python script run in the skills sandbox when a step needs real computation, ReAct only (ADR-249) — and, when the person allows it, reaching the web through one egress proxy that swaps per-run tokens for the person's own connector keys, an unknown host asked with three answers and settled inside the loop (ADR-298).
• Persistent read-only sub-agents with their own instructions, skills and budgets (SUB_AGENTS).

The workboard

A ticket has a lifecycle, a holder and a result (ADR-276, WORKBOARD):

• One row per ticket, shared by its owner and its holder, across seven columns with sub-tickets, comments and a history; the holder can be you, a connected peer, or LIA.
• When LIA holds it, a sweep claims one ticket at a time, runs it in the execution mode the ticket declares, and settles from an explicit result — a quota ceiling or a busy conversation postpones the run, never fails it.
• A run that needs a decision asks instead of refusing: the ticket lands in « To confirm » carrying the exact card the chat would show, and your comment is the answer.

Anticipate

The heartbeat

• LIA takes the initiative when it is worth it: calendar, mail, tasks, weather changes, interests, memories, habits and the workboard are aggregated, a cheap structured decision says whether to speak, at your local time, and a second pass writes it in your voice and language.
• Each source has a switch that says whether it is connected, you set the window and the channels — there is no daily quota: every pass of the window reaches the decision, bounded by the cooldowns (ADR-328) —, rate every notification, and every pass files what it read in your registers (HEARTBEAT_AUTONOME, GUIDE_HEARTBEAT).

Moments served to the minute

• A periodic sweep cannot serve an instant, so a finished meeting or an awaited reply is kept as an anticipated moment, claimed under a lock, revalidated, and served under the full eligibility checker while bypassing only the deferrals.
• Mail watches are answered from the push-driven wake that already holds the Gmail delta (ADR-281, ADR-261).

Routines and reminders

• A scheduled routine or reminder uses the timezone-aware recurrence engine ("every three days", "the 2nd Tuesday of the month").
• A condition routine has no schedule: it is checked at the system's cadence for its source and records a run only when it fires. A weather condition always reads Google Weather and fires only on a change due within the next hours, above a published precipitation threshold, the run told the hour, the day and the source.
• The studio offers one mode at a time, with a week view of actual runs (ADR-268, ADR-322, ADR-265, SCHEDULED_ACTIONS).

Interests and habits, learned with restraint

• An interest is created only on a named ground quoted from your own words, with six exclusion classes and a cap on deletions per run (ADR-166, INTERESTS).
• Habits are learned deterministically from a recurrence ledger, promoted, refreshed or demoted by a nightly job and never on doubt.
• A status you set on a learned window holds for the heartbeat, its scheduling and the assistant's context alike, a missed routine is offered by name, and one learning switch closes every door (ADR-214).

A daily briefing

The home page aggregates your sources in parallel with a per-section cache and an LLM synthesis — including a Workboard card with exact counts of what waits on you, what LIA holds and what is overdue — served by a read-only domain outside the agent graph (BRIEFING_DOMAIN).

Remember

Long-term memory

• Facts are extracted after each conversation, pinned or edited by hand, and injected by relevance with their scores visible in the debug panel (LONG_TERM_MEMORY, MEMORY_RESOLUTION).
• Newly learned standing instructions are pinned automatically. You can edit, unpin or delete them; automatic maintenance respects their protection.
• The planner, the ReAct loop and the phone look them up on purpose through one lookup door that answers what was asked, never just the latest memories (ADR-313).

Personal journals

• Introspective notebooks the assistant keeps in the first person, stratified from raw observations to a user portrait, with an epistemic status per entry and a deferred self-evaluation at zero added LLM cost.
• The portrait is compiled from four sources — memories, interests, learned habits, relationship debriefs — each read under its own gates, and it shows which ones it used (ADR-079, ADR-292, JOURNALS).
• A read tool searches them on demand — directives, patterns and facets, never raw observations (ADR-318).

Knowledge spaces

• Personal document bases in 15+ formats with hybrid search (pgvector cosine + BM25), Google Drive folder sync, a Gmail label as a source, and a system space that indexes the product's own FAQ so LIA can explain itself.
• A document that cannot be indexed says why in your language — a scanned PDF without a text layer names its remedy.
• Any indexed document, paused space or not, attaches to a chat message as a copy from the composer's « + » (ADR-295, GUIDE_RAG_SPACES, ADR-055, ADR-058).

Meetings and minutes

• Record from the phone or the computer while the chat stays usable, with a capture that survives reloads and lost microphones.
• A chain of transcription engines walked at processing time.
• Minutes filled from one of thirty built-in templates or your own, reformatted in place or derived into a second set from the same transcript (ADR-258, ADR-259, MEETINGS).

People

• A 360° relationship lens over open loops, calls, messages and memories, with a written debrief per person built lazily when the card opens (ADR-176, ADR-193, ADR-269).
• Connections between users of the same instance, assistant to assistant — relayed messages delivered by the recipient's own assistant, field-level read-only shares, silent blocking (ADR-180, ADR-182).
• A generated image shared with a connection as a copy, in one click and one transaction, its comment quoted literally in their chat (ADR-316).

What LIA produced is yours

• Generated images, documents and browser screenshots have their own galleries with search, exact totals and a visible retention deadline.
• Clearing a conversation never clears them (ADR-279).
• LIA finds them again when asked and shows them as the chat's own cards (ADR-318).

What you keep is yours too

• A bookmark on every answer copies it with the request that produced it and the answer's date, so it outlives the conversation.
• A Bookmarks tab beside the galleries lists them newest first, with search, an exact total against the account's cap, sharing, a Markdown export and deletion.
• Every kept answer is also indexed in a knowledge space of your own, so LIA cites it weeks later when a question concerns it, and the card shows the indexing state and two named costs — what the answer cost to produce and what indexing it cost, as billed (ADR-282, ADR-291, BOOKMARKS).

Trust it

Three registers, sealed on request

• One row per action (claimed before it happens, closed from an explicit result), one per consultation (which capability read what, when, with what outcome), one per turn.
• Proactive acts and direct reads are recorded too.
• Extractions are complete, never capped.
• An opt-in per-account hash chain makes the registers tamper-evident while preserving the right to erasure, and LIA answers « what did you do? » from them with exact totals (ADR-263, ADR-270, ADR-273, ADR-318, AI_ACT_TRACEABILITY).

Spend that answers to two ceilings

• Every platform-paid token counts against the account's quota and the instance's daily budget.
• A refusal carries a dedicated code and a Retry-After.
• Where each module's spend is recorded is declared and guarded, never inferred.
• The rule covers more than model tokens: every euro the platform pays for a person — a Maps lookup during a call, the briefing's weather, a photo shown, a voice synthesis — reaches their ledger whatever the path. One persistence predicate covers every family the tracker holds, and a counter fails closed into an alert (ADR-216, ADR-272, USAGE_LIMITS).
• Spend uses the price the provider bills: tariffs read from the vendors' pages, a prompt-cache write billed at its price, a pricing window that names its days, a Maps call filed at the SKU its request triggers, and every tariff writer reaching every worker (ADR-306, LLM_PRICING_MANAGEMENT).
• Every reported model attempt keeps the tariff and exchange rate captured when it started. Paid failures, retries and background work reach the same ledger, including work that finishes after a cancelled conversation; missing usage is not invented (TOKEN_TRACKING_AND_COUNTING).

Strong authentication

• WebAuthn passkeys, a TOTP second factor with backup codes, step-up re-authentication on sensitive actions, device sessions with per-device revocation, server-side Redis sessions behind HTTP-only cookies (ADR-143, ADR-144, AUTHENTICATION).
• A federated sign-in proves an address, never a right — it can neither activate nor unblock an account (ADR-002) — and every « who is calling? » reads one resolver (ADR-213).

Your data, by construction

• Credentials are encrypted with Fernet. Logs keep facts, never the words of the people they concern; the guard checks the value rather than the field name (ADR-317).
• A full-account GDPR export is available (ADR-145). External content keeps its provenance through compaction.
• Skill scripts run in a throwaway container. Automated backups have a tested one-command restore (ADR-109, SECURITY).

Exact where it must be

Arithmetic, dates and currencies use tools in both execution modes, never a model's estimate:

• Calculations are parsed and evaluated in exact decimal, with rounding stated.
• Durations are counted between absolute instants across a clock change.
• Currency conversion uses the European Central Bank reference rate with its date (ADR-318).

Failures made visible

• One status vocabulary whose every member is produced and read, one success predicate for the register, the metrics and the ReAct loop, a structural failure marker on the ReAct message, and an honesty directive that names the tool that failed and the exact total, so the response has the recorded failure evidence instead of an unexplained gap (ADR-303).
• Every act is filed under its own turn and stated to the response as the assistant's own (ADR-263).
• No database transaction stays open while a provider answers (ADR-304).

Switches, not redeploys

• Every capability switches off from the admin panel, each declaring where it is enforced.
• A switch removes the capability, never the record (ADR-217, ADR-280).

Administration & Monitoring

The admin interface brings deployed capabilities, accounts, model configuration, budgets and diagnostics into one place. The observability stack adds metrics, logs, traces and alerts. Deployment settings still define which services and capabilities are available.

Admin Dashboard

Real-Time Debug Panel

A 24-section panel embedded in the chat, organised into six groups; an empty section shows "N/A" rather than disappearing.

Built for developers and operators: diagnose, optimise prompts and understand the agent's decisions in real time — no external tool, no log access needed (DEBUG_PANEL).

Observability

• Prometheus: 618 custom metrics (agents, LLM, infrastructure), labelled by route template — a name or a search in an address never becomes a series. A metric nobody can see is a metric nobody acts on: every one must be wired to a Grafana panel, a recording rule or an alert, and a shrink-only ratchet fails the build on a newly blind metric.
• Grafana: 31 dashboards, including product-value and radio cockpits · Loki: structured JSON logs that keep facts, never people's words, shipped by Grafana Alloy (ADR-317) · Tempo: distributed tracing, spans named by the route template · Langfuse: LLM tracing with prompt versions. The whole stack runs on supported versions, pinned by digest.
• Linked signals, a pipeline that watches itself: a log line opens its trace, a trace its logs and metrics, a latency point its exemplar; Loki, Alloy, Tempo and Grafana are scraped on closed keep-lists and LogsNotDelivered fires when lines go missing; every dashboard opens on seven days (logs and traces on four hours) behind one shared menu — ADR-333.
• Probes: liveness (GET /health) split from readiness (GET /ready, 503 unless PostgreSQL and Redis answer) — ADR-115.
• Alerting: a vital core (service, database and Redis down, disk, OOM, 5xx rate, SSE latency, backup failure, public-endpoint and TLS probes, chain self-monitoring) evaluated by Prometheus, emailed by a dedicated Alertmanager, unit-tested with promtool, every alert linking its runbook — ADR-119.
• Per-process memory: every API worker publishes what it holds (lia_worker_memory_bytes, one series per live worker), drawn on the infrastructure dashboard and watched by an alert that names the process; what a process loads is declared, measured on the target host and bounded where it multiplies — the supervisor never imports the application, heavy libraries load where they are used, and the speech engine keeps one resident model per worker (ADR-283).
• Self-diagnostics: a leader-elected self-check of the golden signals, one incident per outage whichever observer saw it first, and a budget-capped diagnosis written in each administrator's language from evidence collected at diagnosis time — metrics, a sanitised log excerpt, the running build, the alert's runbook — shown under its verdict in Settings › Platform health (ADR-247, ADR-266).

See the instance from the operator's side

These three Grafana screenshots were supplied by the project owner and reproduced unchanged. Their figures show the supplied dashboard state; the Grafana manifest records their origin and dimensions.

Grafana — infrastructure and host/container resources.

Grafana — LLM tokens, costs and cache.

Grafana — request origins and rates, account activity, tool usage and router intents.

Built by an AI, Directed by a Human

"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:

Source-line figure: 932,860 physical lines in Python, TypeScript, JavaScript and CSS under apps/api/src and apps/web/src, excluding test directories and *.test.*/*.spec.* files (measured 2026-10-12). Test inventory combines backend collection and the frontend suite; release qualification executes the repository's required gates. The published technical audit does not score security.

• The full story — method, trade-offs, results and what remains to be done, weaknesses included: lia.jeyswork.com/story
• The audit itself — 24 normalized areas mapped to ISO/IEC 25010:2023, every score backed by executed evidence, open worksites included, with the protocol and the full standalone report: docs/audit/

Quick Start

Prerequisites

Every command lives in Taskfile.yml.

Express Setup

# 1. Clone the repository
git clone https://github.com/jgouviergmail/LIA-Assistant.git
cd LIA-Assistant

# 2. Configure environment
cp .env.example .env  # Edit with your API keys

# 3. Full setup (backend + frontend + git hooks)
task setup

# 4. Start all services (API + Web + PostgreSQL + Redis + observability)
task dev

Manual setup (without Task)

# 1. Start the infrastructure
docker compose up -d postgres redis prometheus grafana

# 2. Backend setup
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

# 3. Database migrations
alembic upgrade head

# 4. Frontend setup
cd ../web
pnpm install

# 5. Start the services
# Terminal 1 - Backend:
cd apps/api && uvicorn src.main:app --reload --port 8000

# Terminal 2 - Frontend:
cd apps/web && pnpm dev

Self-Hosting in Production

A guided installer lives at the repository root (ADR-215). It asks a short questionnaire (LAN exposure, your own reverse proxy, or managed HTTPS with Caddy), generates a private .env and Compose overlay, applies the reference seeds atomically, creates the admin and provider keys over stdin, verifies the installation beyond /ready and prints a non-secret report. The experimental speaking avatar is an optional choice, disabled by default; each person then connects their own Simli account. A complete source checkout builds the images locally; an official release directory uses prebuilt digests only when its adjacent manifest is qualified. Resume an interrupted run with ./install.sh --resume, change the routing later with ./install.sh --reconfigure. The shipped .env profiles size the connection pools against the database's memory floor as well as its ceiling, and a guard reads both profiles with the Compose file so the sizing cannot drift (ADR-283).

Full guide: docs/guides/GUIDE_SELF_HOSTING.md — what it installs, every setting, and what to do when a step fails. Production targets include the Raspberry Pi (ARM64) through multi-arch Docker images (linux/amd64,linux/arm64).

Development URLs

Minimal Configuration (.env)

# Database
DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/lia
REDIS_URL=redis://localhost:6379/0

# Security (REQUIRED - change in production)
SECRET_KEY=change-me-in-production-use-openssl-rand-base64-32
FERNET_KEY=your-fernet-key-here

# LLM provider API keys are configured in the Admin UI after first login
# (Settings > Administration > LLM Configuration). At least one provider is required.

# Google OAuth (optional)
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...

# Feature flags (optional, disabled by default unless stated)
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
SUB_AGENTS_ENABLED=false        # Persistent specialized sub-agents
SKILLS_ENABLED=false            # Skills system (agentskills.io standard)
RAG_SPACES_ENABLED=true         # Knowledge spaces (document upload & retrieval)
FCM_NOTIFICATIONS_ENABLED=false # Firebase push notifications

Every optional subsystem is governed by a {FEATURE}_ENABLED flag, checked at startup, at route wiring and at node entry; the full list with defaults is in .env.example.

Architecture

Three layers: a Next.js front end (chat, settings, six languages, SSE streaming, voice) talking over HTTP-only cookies to a FastAPI backend, whose LangGraph graph orchestrates the agents and tools; PostgreSQL (data, checkpoints, pgvector) and Redis (cache, sessions, rate limiting, locks) underneath, with Prometheus, Langfuse, Loki and Tempo watching. The backend follows Domain-Driven Design: one bounded context per domain, each with its router, service, repository and schemas.

Two Execution Modes

Switchable per user from the chat header:

• Pipeline (default) — a Planner decomposes the request into an execution plan (a small DSL with dependencies, conditions and FOR_EACH iteration), a Semantic Validator checks its coherence, tool-level approval flows review the actions that require confirmation, and a Task Orchestrator runs the tools in parallel waves; Bayesian pattern learning shortens the next similar request. Planning and validation precede execution; token use depends on the task and selected models.
• ReAct (⚡) — the model reasons iteratively, calling tools one by one and adapting to each result. Suited to exploratory, research or ambiguous queries; cost and latency depend on the work and selected models. Its iteration budget is extended while the loop keeps producing results, a turn that stops mid-flight closes its own books, the tools it binds are chosen by relevance to the question rather than cut by a cap — or all of them, when the person chose frequent exchanges so the provider's cache reads each turn back from the previous one — and a turn is judged on its result: a gap it declares buys a bounded recovery pass.

graph TD
    A[User Message] --> CP[Compaction]
    CP --> B[Router Node]
    B -->|conversation| C[Response Node]
    B -->|pipeline mode| D[Planner Node]
    B -->|react mode| R1[ReAct Setup]
    D -->|empty plan| C
    D --> E[Semantic Validator]
    E -->|ambiguous| CL[Clarification]
    CL --> E
    E -->|replan| D
    E --> F{Approval Gate}
    F --> G[Task Orchestrator]
    G --> H[Domain Agents + Tools]
    G -->|drafts| HD[HITL Dispatch]
    G -->|bulk action| FE[FOR_EACH Confirm]
    FE -->|approved| G
    H --> I[Initiative]
    HD --> I
    I --> C
    R1 --> R2[ReAct Call Model]
    R2 -->|tool_calls| R3[ReAct Execute Tools]
    R3 --> R2
    R3 -->|draft| HD
    R2 -->|declared gap| R5[ReAct Recovery]
    R5 --> R2
    R2 -->|done| R4[ReAct Finalize]
    R4 --> I
    C --> J[SSE Stream]

Loading

Code Structure

apps/api/src/
├── core/                 # Settings composed per domain, constants, i18n tables, recurrence engine
├── domains/              # Bounded contexts (DDD); shared helpers stay separate
│   ├── agents/           # The LangGraph graph: nodes (router, planner, react ×4, response…), tools, prompts, orchestration
│   ├── connectors/       # Google, Apple and Microsoft clients behind one provider resolver
│   ├── heartbeat/ moments/ scheduled_actions/ reminders/ habits/ interests/ briefing/       # initiative
│   ├── memories/ journals/ rag_spaces/ meetings/ relations/ peers/ workboard/ attachments/  # what LIA keeps
│   ├── auth/ users/ usage_limits/ capabilities/ feature_switches/ diagnostics/              # control
│   └── voice/ skills/ plugins/ user_mcp/ telephony/ document_generation/ image_generation/ …
└── infrastructure/       # Cross-cutting: cache and Redis key families, LLM factory and providers,
                          # MCP client pool, browser pool, rate limiting, scheduler, startup steps, observability
apps/web/src/             # Next.js App Router under app/[lng]/, components, hooks, stores, six locales
apps/mobile/              # Capacitor shells for Android and iOS, loading a self-hosted server
infrastructure/           # Compose stacks, database seeds, observability config, backups, Caddy
scripts/                  # Release, audit, deployment and measurement tooling
docs/                     # Architecture, technical documents, guides, runbooks, ADRs, the public audit

Key Design Patterns

The long version: How does LIA work? (public architecture guide), ARCHITECTURE.md, ARCHITECTURE_LANGRAPH.md, and the living maps — the functional map, the technical map and the history of every decision, also published in six languages on the public site.

Technologies

Stack

The UI is responsive by design — desktop, tablet and phone — with touch-friendly, mobile-first components.

Supported LLM Providers

The model catalogue lives in the database, curated from vendored public registries and editable from the admin panel; every row states where its capabilities came from (ADR-244). Reasoning depth has one stored shape for every provider (ADR-245); a model family is declared once, and a caller that needs two sentences asks for no reasoning rather than a small budget — a reasoning model bills its thinking inside max_tokens (ADR-285). What a prompt says is what the code enforces, and nothing else: every placeholder has a producer, every published bound is the applied bound, prose never lives in a .py (ADR-284). Every prompt follows one layout — stable before volatile, one boundary each provider adapter translates into its own cache mechanism, no cache write nobody reads — and what each model generation accepts is measured on its API and declared once (ADR-309, ADR-306).

Local Models as First-Class Models

Compatible chat models hosted on your own machine can serve processing slots whose required capabilities they meet. Image generation, embeddings, Live and native decision providers have their own supported paths. Local inference depends on the chosen model and host resources. LIA drives Ollama through its native API rather than an OpenAI compatibility layer (ADR-267):

• Thinking is controlled, not endured — the configured depth reaches the server as think, including switching it off, and the thinking trace comes back separated from the answer.
• The server declares the capabilities — tools, vision, thinking and context length are read from the tag listing, so a depth never reaches a model that cannot think and a control a local model would ignore is not offered.
• The context window belongs to the configured slot (ADR-278) — a frugal router and a generous responder can share one model with different windows; it is the number LIA asks for and the number it counts with.

Quality: Tests, CI/CD, Security

Tests

task test:backend:unit:fast        # fast unit suite, parallel (what the pre-commit hook runs)
task test:backend:unit:coverage    # the CI command verbatim, including the coverage floor
task test:backend:integration      # requires PostgreSQL + Redis
task test:backend:agents           # LangGraph agent suite
task test:frontend                 # vitest
task test:e2e                      # Playwright + axe journeys (hermetic, mocked API)

Tests are risk-driven and behavioural: a module never disables itself on a missing provider key, a test double that receives a coroutine owns it, and an unawaited coroutine or a post-summary warning is a failure (GUIDE_TESTING).

CI/CD

Two layers: a local pre-commit hook (fast, on staged files) and a GitHub Actions pipeline on every push and PR to main. The workflow orchestrates and the Taskfile implements: every CI step is a task <name> call, so the pipeline runs literally the command a developer runs, and a guard fails on any inline step.

Pre-commit (local)              GitHub Actions CI
===================             ==================
.bak files check                Lint Backend (Ruff + Black + MyPy strict)
Secrets grep                    Lint Frontend (ESLint + TypeScript)
Ruff + Black + MyPy             Fast unit tests + coverage floor
Fast unit tests                 Integration tests (PostgreSQL + Redis)
Critical pattern detection      Agents suite
i18n keys sync                  Code hygiene (i18n, Alembic, lockfiles, patterns, docs)
Alembic migration conflicts     Docker build smoke test
.env.example completeness       Secret scan (Gitleaks)
ESLint + TypeScript check       ──────────────────────
Pre-push: secret scan           Security workflow (weekly)
                                  CodeQL (Python, JS/TS, Actions)
                                  Dependency audit (pip-audit + pnpm audit)
                                  Trivy filesystem scan
                                  SBOM generation
                                Dependency watch (weekly, ADR-331)
                                E2E + a11y matrix: Chromium · Firefox · WebKit (weekly)

Full details: CI/CD documentation.

Security

These references describe implemented controls, not a GDPR/AI Act legal opinion, OWASP or ISO certification, or a security-audit score. The public 8.3/10 audit measures 24 technical-quality areas against an ISO/IEC 25010:2023-inspired grid and explicitly excludes security.

Reporting a vulnerability — do not open a GitHub issue. Write to liamyassistant@gmail.com with a description, the steps to reproduce and the potential impact; we answer within 48 hours. Policy and supported versions: SECURITY.md.

Performance

Instrumentation and caching are in place — per-node message windowing, LLM context compaction with a threshold derived from the response model's window, prompt caching shaped for every provider mechanism (breakpoints, explicit markers, implicit prefixes) with an optional cross-turn cache for ReAct, asymmetric Gemini embeddings, parallel execution of independent domains, persistent HTTP pools — all instrumented in production. The perceived response time is dominated by the LLM call cascade (seconds to tens of seconds depending on the request and the hardware); that is the optimisation programme in progress. The technical audit scores performance 7.5/10: no sustained load campaign has been executed yet, and the figures will be published when one has.

Documentation

Architecture Decision Records

341 ADR files (ADR-001 through ADR-342 — ADR-008 has no separate file) record every major architectural decision with its context, the alternatives and, increasingly, the production measurement that motivated it. Three to start with, and the full index:

• ADR-070: ReAct Execution Mode — why two execution modes rather than one
• ADR-263: Execution Authority Chain and Effect Register — how every act is claimed, closed and recorded
• ADR-184: Published Bounds and Non-Prescriptive Verdicts — an enforced-but-hidden bound is a trap, not a contract

Contributing

Contributions are welcome — bug fixes, features, documentation, tests, translations in the six supported languages, performance work. Start with the Contributing Guide.

git clone https://github.com/YOUR-USERNAME/LIA-Assistant.git && cd LIA-Assistant
git checkout -b feature/my-feature
task setup                          # backend + frontend + git hooks
task test:backend:unit:fast         # develop and test
git commit -m "feat(agents): add weather forecast agent"   # Conventional Commits
git push origin feature/my-feature  # then open a PR

• Python: Black + Ruff + MyPy strict · TypeScript: ESLint + Prettier · Commits: Conventional Commits
• Before pushing: task ci:fast runs every CI gate that needs no service; task pre-commit is what the git hook runs
• Rules that are not stylistic: read the Systemic Rules in CLAUDE.md — each one closes a bug class measured in production, and a guard enforces most of them

Support

Also: the documentation index, the practical guides and the operational runbooks.

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) — see LICENSE.

A commercial license is available for organizations that cannot comply with AGPL-3.0 terms: contact liamyassistant@gmail.com.

Acknowledgments

LIA stands on excellent open source work: Python, FastAPI, LangGraph and LangChain, SQLAlchemy, Pydantic, Alembic, PostgreSQL with pgvector, Redis, structlog, Edge TTS, sherpa-onnx, Docker; Node.js, Next.js, React, TypeScript, TailwindCSS, Radix UI, TanStack Query, react-i18next; Prometheus, Grafana, Loki, Tempo and Langfuse; and the Model Context Protocol, agentskills.io and Agent Plugins open standards.

LIA — Your life. Your AI. Your rules.

Built with ❤️ using Python, FastAPI, LangGraph, Next.js and Node.js

Back to top