2026-04-12
Gen AIBeGuru AI — Technical Narrative: mental model, runtime & state (không phải README)
Tài liệu kiến trúc nội bộ chuyển thành blog: hành vi runtime, state nằm đâu, luồng dữ liệu, trade-off, hạn chế và North Star — bám SSOT repo beguru-ai/docs.
Ý tưởng cốt lõi
Stateless HTTP · stateful disk
Luồng LLM
OpenRouter · Agno registry
Chân lý dự án
.guru · pins · context pack
SSOT
beguru-ai/docs
Đối tượng: kỹ sư onboarding hoặc review kiến trúc. Phạm vi: hành vi runtime và mô hình nhận thức của service trong repo beguru-ai. Không phải: OpenAPI đầy đủ (xem API_SPEC.md), marketing, hay danh sách công nghệ.
Tóm lược
- beguru-ai là HTTP service Python (FastAPI/AgentOS) điều phối agent PM/Engineer; suy luận LLM chủ yếu qua OpenRouter; chân lý dự án bền nằm trên đĩa (
.guru/, design-system), không phải DB hội thoại replay vào mọi prompt. - State cho model: phần lớn từ
messagesdo client gửi lại + nén (ContextCompressor) + pins + đọc file theooutput_path. - Bài này là bản blog hoá
docs/TECHNICAL_NARRATIVE.mdtrong repo; khi lệch code, ưu tiên repo.
1. TL;DR
- Hệ thống là gì: service HTTP Python chạy lâu dài (FastAPI qua Agno AgentOS), điều phối agent theo vai (PM, Engineer) để chạy luồng LLM: thu thập yêu cầu và sinh code xuống cây project thật.
- Sản phẩm ra gì: mã nguồn và artifact có cấu trúc dưới
projects_root_dir(Next.js, Go,.guru/), cộng stream text (kiểu SSE) về client. - Ý kiến trúc chính (1–2 câu): engine stateless theo request trên filesystem stateful: server không giữ toàn bộ transcript như session store cho inference; client gửi lại history; sự thật “sản phẩm là gì” bền vững nằm trên đĩa (và trong pins), không phải DB hội thoại server-side tự động đổ vào mọi prompt.
2. System Overview
Vấn đề: đi từ thảo luận ngôn ngữ tự nhiên tới repo cụ thể (UI + tuỳ chọn API) có rào chắn (template, khối spec, build state) mà không phải tự nối prompt và ghi file từng lượt.
Hành vi runtime: lúc deploy, process Uvicorn nạp Settings, khởi tạo SQLite (bảng Agno), dựng CodingTeam, mount app FastAPI của AgentOS. Request HTTP vào routers (freetext, workflows, …). Luồng sản phẩm chính mặc định là theo request: mỗi call mang payload đủ (đặc biệt messages đầy đủ cho chat/generate) để server nén, ghim, compose prompt, gọi OpenRouter, stream, và ghi file khi chạy Engineer. Langfuse/logging đi kèm nhưng không đổi luồng điều khiển cốt lõi.
Khác app server truyền thống: không có “một dòng session user” chứa toàn bộ hội thoại cho input model. State hội thoại cho LLM được dựng lại từ body request (+ pins từ đĩa). Phần truyền thống còn lại: JSON kiểu REST, một process mỗi đơn vị deploy, và file trên đĩa là nơi lưu artifact phần mềm đã sinh.
3. Mental Model (quan trọng)
Hệ thống giống một dịch vụ biên dịch chuyên biệt với “cửa chat” phía trước: client nộp lô bằng chứng (messages, path, overlay tuỳ chọn). Service chuẩn hoá và cắt (ContextCompressor), xếp lớp context máy (pins, đoạn file), gọi model từ xa (OpenRouter), và khi sinh code thì phát ra ghi file xuống workspace — giống artifact biên dịch, nhưng “trình biên dịch” không deterministic và stream.
Bộ phận chuyển động chính: HTTP routers → pipeline context → stream OpenRouterModel → (tuỳ chọn) ghi filesystem và static check. AgentOS/Agno cung cấp đăng ký agent; đường chạy LLM chủ đạo là tích hợp OpenRouter tùy chỉnh, không phải vòng Agno run() đầy đủ kèm memory built-in (xem mục hạn chế).
Kích hoạt: HTTP request (UI/CLI/test). Không bắt buộc scheduler nội bộ cho path chat/codegen chính.
Luồng dữ liệu khái niệm: Vào → JSON (messages, output_path, …) + Settings từ env + đọc projects_root_dir → Ra → stream SSE + ghi file project + log/trace.
4. Runtime Architecture (lớp)
Interface (API): route /api/...; client JSON, một số path stream; contract trong API_SPEC.md. Middleware CORS, log, Langfuse request id, quota (không đồng nhất mọi route).
Execution (agents/services): PM — hội thoại spec, tag, handoff ## BEGURU_FE_SPEC; Engineer — generate-code, edit-code, Go; không bắt buộc “session PM” server ngoài payload. Pipeline context (compressor, pins, context pack Next.js) là biến đổi deterministic trước LLM. Validation ví dụ run_nextjs_static_check chạy trên host — không tương đương CI container.
State: SQLite — session/workflow/tuỳ chọn persist summary; summary đã persist không tự prepend lại chat (tránh lệch thread — MEMORY_AND_CONTEXT_LAYERS.md). Đĩa — MASTER, BUILD_STATE, PRODUCT_PLAN, beguru_chat_context.json, code: nguồn chân lý giữa các lượt. RAM request — không có RAM hội thoại xuyên request cho freetext.
Phụ thuộc ngoài: OpenRouter (mọi LLM chính); Langfuse tuỳ chọn; MinIO/URL fetch khi bật.
5. State & Data Flow
State nằm đâu: xem bảng trong bản EN hoặc repo — tóm lại: inference dựa vào messages, sau nén/pin/pack thì đĩa là truth cho repo.
Giả định: nếu client bỏ turn cũ, server không khôi phục từ SQLite cho cùng một PM prompt — trừ khi tính năng tương lai thay đổi.
Thứ tự build context: RawHistory → CompressedHistory → PinnedLayer → ContextPack (Engineer).
Luồng FE điển hình: client giữ history → POST .../chat → stream → client cập nhật history → sau đó POST .../generate-code + output_path → pack từ đĩa + messages → stream → ghi file.
6. Execution Flow
PM chat: request có messages → validate/enrich/quota → compressor → pins → prompt PM → OpenRouter stream → text (có tag/block để client parse); không bắt buộc ghi file.
Generate Next.js: messages + output_path → resolve path → context pack → Engineer stream → ghi file theo thứ tự stream → tuỳ chọn static check.
Edge: ngưỡng nén sai; artifact đĩa thiếu/cũ; static check fail nhưng HTTP vẫn 200 — client đọc payload có cấu trúc. Pipeline Go là gate khác, không trùng một phát với FE.
7. Component Breakdown
| Thành phần | Vai trò | Ghi chú |
|---|---|---|
| FastAPI (AgentOS) | HTTP, router | src/api/main.py |
| Routers | freetext, workflows, … | API_SPEC.md |
| CodingTeam / agents | PM, Engineer | src/agents/ |
| OpenRouterModel | Stream/completion | Phụ thuộc ngoài |
| ContextCompressor | Giới hạn độ dài history | Settings |
| Freetext pins & context pack | Ghép context deterministic | src/components/freetext/ |
| Templates | Baseline Next/Go | templates/ |
| SQLite | Agno + persist tuỳ chọn | Không replay chat đầy đủ |
| Skill manifest | Prompt segments | Startup |
8. Key Design Decisions
- History do client mang: scale ngang đơn giản; trade-off payload lớn, client phải nhất quán.
- Artifact-first (đĩa + pins): git-friendly; trade-off contract file/parser chặt.
- OpenRouter một cổng: đơn giản vận hành; trade-off phụ thuộc nhà cung cấp.
- Nén trước, pin sau: không mất khối cấu trúc; trade-off hai bước khi debug.
- Persist summary không auto-reinject: tránh lệch thread; trade-off storage chưa mang lại recall user ngay.
9. Limitations (thẳng thắn)
- Không có memory hội thoại server-first cho inference mặc định; cross-session mạnh cần đĩa + client hoặc tương lai semantic memory (
ADR-0002-memory-oss.md). - Agno memory không là xương sống vận hành mô tả ở đây — coi Agno là framework/registry.
- Không sandbox cô lập mặc định cho code user; static check trên môi trường host.
- Codegen non-deterministic.
- Vòng autonomous đa bước (plan→act→verify→retry) không là một primitive API duy nhất — client/workflow nối bước.
10. North Star
- MemoryPlane + mem0/vector, scoped user/project, bổ sung đĩa.
- Graph/workflow bền (LangGraph; Temporal khi cần durable) cho Plan→edit→chạy lệnh→observe→checkpoint.
- Sandbox npm/go test/build, stdout/stderr làm observation.
- OTel + Langfuse theo node graph.
11. References (repo beguru-ai)
| Tài liệu | Mục đích |
|---|---|
docs/API_SPEC.md | Contract HTTP, output_path |
docs/ARCHITECTURE_RUNTIME.md | Runtime, deploy |
docs/MEMORY_AND_CONTEXT_LAYERS.md | Pipeline, pins, đĩa |
docs/ADR-0002-memory-oss.md | Mem0/LangGraph — chưa áp dụng mặc định |
docs/TROUBLESHOOTING.md | Vận hành |
docs/TECHNICAL_NARRATIVE.md | Bản SSOT narrative (tiếng Anh) |
Blog và plan nội bộ chỉ mô tả roadmap; code + docs/ trong repo là chuẩn khi xung đột.