# phamhanam/lifemate architecture

> Architecture diagram of the GitHub repository phamhanam/lifemate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/phamhanam/lifemate
- Repository: https://github.com/phamhanam/lifemate

## Overview

LifeMate is an offline, per-sample agent that turns Vietnamese audio and sample context into ordered tool calls and a state hash. The CLI loads samples and wires the five stages; the pipeline coordinates perception, context building, planning, and guarded execution, then returns a snapshot for JSONL submission. The stages share typed contracts rather than importing each other. The README documents the stage boundaries and tool-environment constraints; unsampled stage internals are represented only where documented or supported by the source index.

Main entry points: [`lifemate/pipeline.py`](https://github.com/phamhanam/lifemate/blob/main/lifemate/pipeline.py) (Agent pipeline), [`lifemate/cli.py`](https://github.com/phamhanam/lifemate/blob/main/lifemate/cli.py) (CLI runner), [`lifemate/stage3_planning/planner.py`](https://github.com/phamhanam/lifemate/blob/main/lifemate/stage3_planning/planner.py) (LLM planner), [`lifemate/stage4_execution/executor.py`](https://github.com/phamhanam/lifemate/blob/main/lifemate/stage4_execution/executor.py) (Tool executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and contracts"]
  node_cli["CLI runner<br/>[cli.py]"]
  node_config["Runtime config<br/>[config.py]"]
  node_dataset["Sample reader<br/>[dataset.py]"]
  node_contracts["Stage contracts<br/>[contracts.py]"]
  node_timing["Timeout controls<br/>[timing.py]"]
  node_pipeline["Agent pipeline<br/>[pipeline.py]"]
end

subgraph group_perception["Perception"]
  node_asr["Whisper ASR<br/>[asr.py]"]
  node_perceiver["Audio perception<br/>[perceiver.py]"]
end

subgraph group_context["Context"]
  node_catalog["Tool catalog<br/>[catalog.py]"]
  node_context_builder["Context builder<br/>[builder.py]"]
  node_temporal["Time anchors<br/>[temporal.py]"]
end

subgraph group_planning["Planning"]
  node_planner["LLM planner<br/>[planner.py]"]
  node_fewshot["Few-shot index<br/>[fewshot.py]"]
  node_prompt["Prompt builder<br/>[prompt.py]"]
  node_llm["Local LLM<br/>[llm.py]"]
  node_parser["Action parser<br/>[parser.py]"]
end

subgraph group_execution["Execution"]
  node_executor["Tool executor<br/>[executor.py]"]
  node_gateway["Tool gateway<br/>[gateway.py]"]
  node_grounding["Grounding guard<br/>[grounding.py]"]
end

subgraph group_submission["Submission"]
  node_writer["JSONL writer<br/>[writer.py]"]
end

node_user(("Sample provider"))
node_toolenv["ToolEnv"]

node_user -->|"supplies split"| node_cli
node_cli -->|"loads settings"| node_config
node_cli -->|"reads samples"| node_dataset
node_cli -->|"builds pipeline"| node_pipeline
node_cli -->|"writes results"| node_writer
node_pipeline -->|"uses settings"| node_config
node_pipeline -->|"uses interfaces"| node_contracts
node_pipeline -->|"enforces deadlines"| node_timing
node_pipeline -->|"perceives audio"| node_perceiver
node_pipeline -->|"builds context"| node_context_builder
node_pipeline -->|"plans actions"| node_planner
node_pipeline -->|"opens session"| node_executor
node_perceiver -->|"transcribes audio"| node_asr
node_context_builder -->|"selects tools"| node_catalog
node_context_builder -->|"derives anchors"| node_temporal
node_planner -->|"builds prompts"| node_prompt
node_planner -->|"retrieves examples"| node_fewshot
node_planner -->|"queries model"| node_llm
node_planner -->|"parses output"| node_parser
node_executor -->|"validates and calls"| node_gateway
node_executor -->|"checks grounding"| node_grounding
node_executor -->|"creates environment"| node_toolenv
node_pipeline -.->|"returns result"| node_writer
node_cli -.->|"passes results"| node_contracts

click node_cli "https://github.com/phamhanam/lifemate/blob/main/lifemate/cli.py"
click node_config "https://github.com/phamhanam/lifemate/blob/main/lifemate/core/config.py"
click node_dataset "https://github.com/phamhanam/lifemate/blob/main/lifemate/core/dataset.py"
click node_contracts "https://github.com/phamhanam/lifemate/blob/main/lifemate/core/contracts.py"
click node_timing "https://github.com/phamhanam/lifemate/blob/main/lifemate/core/timing.py"
click node_pipeline "https://github.com/phamhanam/lifemate/blob/main/lifemate/pipeline.py"
click node_asr "https://github.com/phamhanam/lifemate/blob/main/lifemate/stage1_perception/asr.py"
click node_perceiver "https://github.com/phamhanam/lifemate/blob/main/lifemate/stage1_perception/perceiver.py"
click node_catalog "https://github.com/phamhanam/lifemate/blob/main/lifemate/stage2_context/catalog.py"
click node_context_builder "https://github.com/phamhanam/lifemate/blob/main/lifemate/stage2_context/builder.py"
click node_temporal "https://github.com/phamhanam/lifemate/blob/main/lifemate/stage2_context/temporal.py"
click node_planner "https://github.com/phamhanam/lifemate/blob/main/lifemate/stage3_planning/planner.py"
click node_fewshot "https://github.com/phamhanam/lifemate/blob/main/lifemate/stage3_planning/fewshot.py"
click node_prompt "https://github.com/phamhanam/lifemate/blob/main/lifemate/stage3_planning/prompt.py"
click node_llm "https://github.com/phamhanam/lifemate/blob/main/lifemate/stage3_planning/llm.py"
click node_parser "https://github.com/phamhanam/lifemate/blob/main/lifemate/stage3_planning/parser.py"
click node_executor "https://github.com/phamhanam/lifemate/blob/main/lifemate/stage4_execution/executor.py"
click node_gateway "https://github.com/phamhanam/lifemate/blob/main/lifemate/stage4_execution/gateway.py"
click node_grounding "https://github.com/phamhanam/lifemate/blob/main/lifemate/stage4_execution/grounding.py"
click node_writer "https://github.com/phamhanam/lifemate/blob/main/lifemate/stage5_submission/writer.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_config,node_dataset,node_contracts,node_timing,node_pipeline toneBlue
class node_asr,node_perceiver toneAmber
class node_catalog,node_context_builder,node_temporal toneMint
class node_planner,node_fewshot,node_prompt,node_llm,node_parser toneRose
class node_executor,node_gateway,node_grounding,node_user,node_toolenv toneIndigo
class node_writer toneTeal
```

## Components

### Runtime and contracts

- [CLI runner](https://github.com/phamhanam/lifemate/blob/main/lifemate/cli.py): `lifemate/cli.py`
- [Runtime config](https://github.com/phamhanam/lifemate/blob/main/lifemate/core/config.py): `lifemate/core/config.py`
- [Sample reader](https://github.com/phamhanam/lifemate/blob/main/lifemate/core/dataset.py): `lifemate/core/dataset.py`
- [Stage contracts](https://github.com/phamhanam/lifemate/blob/main/lifemate/core/contracts.py): `lifemate/core/contracts.py`
- [Timeout controls](https://github.com/phamhanam/lifemate/blob/main/lifemate/core/timing.py): `lifemate/core/timing.py`
- [Agent pipeline](https://github.com/phamhanam/lifemate/blob/main/lifemate/pipeline.py): `lifemate/pipeline.py`

### Perception

- [Whisper ASR](https://github.com/phamhanam/lifemate/blob/main/lifemate/stage1_perception/asr.py): `lifemate/stage1_perception/asr.py`
- [Audio perception](https://github.com/phamhanam/lifemate/blob/main/lifemate/stage1_perception/perceiver.py): `lifemate/stage1_perception/perceiver.py`

### Context

- [Tool catalog](https://github.com/phamhanam/lifemate/blob/main/lifemate/stage2_context/catalog.py): `lifemate/stage2_context/catalog.py`
- [Context builder](https://github.com/phamhanam/lifemate/blob/main/lifemate/stage2_context/builder.py): `lifemate/stage2_context/builder.py`
- [Time anchors](https://github.com/phamhanam/lifemate/blob/main/lifemate/stage2_context/temporal.py): `lifemate/stage2_context/temporal.py`

### Planning

- [LLM planner](https://github.com/phamhanam/lifemate/blob/main/lifemate/stage3_planning/planner.py): `lifemate/stage3_planning/planner.py`
- [Few-shot index](https://github.com/phamhanam/lifemate/blob/main/lifemate/stage3_planning/fewshot.py): `lifemate/stage3_planning/fewshot.py`
- [Prompt builder](https://github.com/phamhanam/lifemate/blob/main/lifemate/stage3_planning/prompt.py): `lifemate/stage3_planning/prompt.py`
- [Local LLM](https://github.com/phamhanam/lifemate/blob/main/lifemate/stage3_planning/llm.py): `lifemate/stage3_planning/llm.py`
- [Action parser](https://github.com/phamhanam/lifemate/blob/main/lifemate/stage3_planning/parser.py): `lifemate/stage3_planning/parser.py`

### Execution

- [Tool executor](https://github.com/phamhanam/lifemate/blob/main/lifemate/stage4_execution/executor.py): `lifemate/stage4_execution/executor.py`
- [Tool gateway](https://github.com/phamhanam/lifemate/blob/main/lifemate/stage4_execution/gateway.py): `lifemate/stage4_execution/gateway.py`
- [Grounding guard](https://github.com/phamhanam/lifemate/blob/main/lifemate/stage4_execution/grounding.py): `lifemate/stage4_execution/grounding.py`

### Submission

- [JSONL writer](https://github.com/phamhanam/lifemate/blob/main/lifemate/stage5_submission/writer.py): `lifemate/stage5_submission/writer.py`

### Other components

- **Sample provider**
- **ToolEnv**

## Connections

- Sample provider → CLI runner: supplies split (evidence: `README.md`)
- CLI runner → Runtime config: loads settings (evidence: `lifemate/cli.py`)
- CLI runner → Sample reader: reads samples (evidence: `lifemate/cli.py`)
- CLI runner → Agent pipeline: builds pipeline (evidence: `lifemate/cli.py`)
- CLI runner → JSONL writer: writes results (evidence: `lifemate/cli.py`)
- Agent pipeline → Runtime config: uses settings (evidence: `lifemate/pipeline.py`)
- Agent pipeline → Stage contracts: uses interfaces (evidence: `lifemate/pipeline.py`)
- Agent pipeline → Timeout controls: enforces deadlines (evidence: `lifemate/pipeline.py`)
- Agent pipeline → Audio perception: perceives audio (evidence: `lifemate/pipeline.py`)
- Agent pipeline → Context builder: builds context (evidence: `lifemate/pipeline.py`)
- Agent pipeline → LLM planner: plans actions (evidence: `lifemate/pipeline.py`)
- Agent pipeline → Tool executor: opens session (evidence: `lifemate/pipeline.py`)
- Audio perception → Whisper ASR: transcribes audio (evidence: `lifemate/stage1_perception/__init__.py`)
- Context builder → Tool catalog: selects tools (evidence: `lifemate/stage2_context/builder.py`)
- Context builder → Time anchors: derives anchors (evidence: `lifemate/stage2_context/builder.py`)
- LLM planner → Prompt builder: builds prompts (evidence: `lifemate/stage3_planning/planner.py`)
- LLM planner → Few-shot index: retrieves examples (evidence: `lifemate/stage3_planning/planner.py`)
- LLM planner → Local LLM: queries model (evidence: `lifemate/stage3_planning/planner.py`)
- LLM planner → Action parser: parses output (evidence: `lifemate/stage3_planning/planner.py`)
- Tool executor → Tool gateway: validates and calls (evidence: `lifemate/stage4_execution/executor.py`)
- Tool executor → Grounding guard: checks grounding (evidence: `lifemate/stage4_execution/executor.py`)
- Tool executor → ToolEnv: creates environment (evidence: `lifemate/stage4_execution/executor.py`)
- Agent pipeline → JSONL writer: returns result (evidence: `README.md`)
- CLI runner → Stage contracts: passes results (evidence: `README.md`)
