datn-cli 0.2.2__tar.gz

datn_cli-0.2.2/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: datn-cli
+Version: 0.2.2
+Summary: One-command distribution for the datn multi-agent assistant (hides docker compose).
+Author: ngoquan0904
+License: MIT
+Project-URL: Homepage, https://github.com/ngoquan0904/datn-cli
+Keywords: cli,docker,compose,ai-assistant,distribution
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: jinja2>=3.1
+
+# datn-cli
+
+Cài hệ trợ lý đa tác tử **datn** bằng 1 lệnh — CLI ẩn docker compose. Không cần source code.
+
+## Cài đặt (1 lệnh)
+
+**macOS / Linux:**
+```bash
+curl -fsSL https://raw.githubusercontent.com/ngoquan0904/datn-cli/main/install.sh | sh
+```
+
+**Windows (PowerShell):**
+```powershell
+irm https://raw.githubusercontent.com/ngoquan0904/datn-cli/main/install.ps1 | iex
+```
+
+Script tự cài: Python 3.9+, pipx, Docker (Linux) / WSL2+Docker Desktop (Windows), rồi `datn-cli`.
+
+## Chạy
+
+```bash
+datn init     # nhập API key cho LLM + embedding (chọn provider)
+datn up       # pull images + khởi động + chờ healthy (lần đầu mất vài phút)
+datn open     # mở http://localhost:5173
+```
+
+Trong `datn init` bạn chỉ cần **nhập API key**. Embedding dimension tự dò.
+Gmail/Calendar cấu hình sau trong **Settings** của web UI (upload `client_secret.json`).
+
+## Lệnh hay dùng
+
+| Lệnh | Việc |
+|---|---|
+| `datn doctor` | Kiểm tra Docker, ports, cấu hình |
+| `datn logs agent-api` | Xem log 1 service |
+| `datn down` | Dừng (giữ data) |
+| `datn config llm` | Đổi LLM provider/model/key |
+| `datn config embedding` | Đổi embedding (đổi dim → cần `datn reset`) |
+| `datn update --tag vX.Y.Z` | Cập nhật phiên bản image |
+| `datn reset` | Xoá data (RAG + chat history) |
+| `datn uninstall` | Gỡ data + cấu hình |
+
+## Self-host LLM/Embedding
+
+Chọn provider `selfhost` trong `datn init`, nhập `base_url` (OpenAI-compatible, vd vLLM/llama.cpp/Ollama).
+`localhost`/`127.0.0.1` tự đổi sang `host.docker.internal` để container gọi được host.
+
+## Troubleshooting
+
+| Triệu chứng | Cách xử lý |
+|---|---|
+| **Docker chưa cài** (macOS) | Tải Docker Desktop: https://www.docker.com/products/docker-desktop/ — script không tự cài được file .dmg |
+| **`permission denied` Docker (Linux)** | Đăng xuất + đăng nhập lại 1 lần (đã thêm bạn vào nhóm `docker`). Kiểm tra: `datn doctor` |
+| **WSL2 chưa có (Windows)** | Chạy lại `install.ps1` sau khi **khởi động lại máy** (script đã chạy `wsl --install`) |
+| **Port bận** (5000/8000/5173/5432/6333/9000) | `datn doctor` báo port + tiến trình. Đóng app chiếm port hoặc dừng stack cũ |
+| **Đĩa đầy khi pull** | Cần ~5GB trống cho images. Dọn ổ rồi `datn up` lại |
+| **Đổi embedding → lỗi dim** | `datn reset` (xoá data) → `datn init` → `datn up`. Đổi dim làm vỡ Qdrant collection |
+| **News/Travel báo "chưa cấu hình"** | Thiếu Tavily/SerpApi key — chạy `datn config tavily` / `datn config serpapi` (optional) |
+| **Image pull lỗi / tag không tồn tại** | Kiểm tra tag trong `~/.datn/provider.lock`; thử `datn update --tag latest` |
+
+## Yêu cầu hệ thống
+- RAM ≥ 4GB (Qdrant + Postgres + backend).
+- Đĩa trống ≥ 5GB (images ~2-4GB).
+- Kết nối Internet (pull images + gọi LLM API).

datn_cli-0.2.2/README.md

@@ -0,0 +1,64 @@
+# datn-cli
+
+Cài hệ trợ lý đa tác tử **datn** bằng 1 lệnh — CLI ẩn docker compose. Không cần source code.
+
+## Cài đặt (1 lệnh)
+
+**macOS / Linux:**
+```bash
+curl -fsSL https://raw.githubusercontent.com/ngoquan0904/datn-cli/main/install.sh | sh
+```
+
+**Windows (PowerShell):**
+```powershell
+irm https://raw.githubusercontent.com/ngoquan0904/datn-cli/main/install.ps1 | iex
+```
+
+Script tự cài: Python 3.9+, pipx, Docker (Linux) / WSL2+Docker Desktop (Windows), rồi `datn-cli`.
+
+## Chạy
+
+```bash
+datn init     # nhập API key cho LLM + embedding (chọn provider)
+datn up       # pull images + khởi động + chờ healthy (lần đầu mất vài phút)
+datn open     # mở http://localhost:5173
+```
+
+Trong `datn init` bạn chỉ cần **nhập API key**. Embedding dimension tự dò.
+Gmail/Calendar cấu hình sau trong **Settings** của web UI (upload `client_secret.json`).
+
+## Lệnh hay dùng
+
+| Lệnh | Việc |
+|---|---|
+| `datn doctor` | Kiểm tra Docker, ports, cấu hình |
+| `datn logs agent-api` | Xem log 1 service |
+| `datn down` | Dừng (giữ data) |
+| `datn config llm` | Đổi LLM provider/model/key |
+| `datn config embedding` | Đổi embedding (đổi dim → cần `datn reset`) |
+| `datn update --tag vX.Y.Z` | Cập nhật phiên bản image |
+| `datn reset` | Xoá data (RAG + chat history) |
+| `datn uninstall` | Gỡ data + cấu hình |
+
+## Self-host LLM/Embedding
+
+Chọn provider `selfhost` trong `datn init`, nhập `base_url` (OpenAI-compatible, vd vLLM/llama.cpp/Ollama).
+`localhost`/`127.0.0.1` tự đổi sang `host.docker.internal` để container gọi được host.
+
+## Troubleshooting
+
+| Triệu chứng | Cách xử lý |
+|---|---|
+| **Docker chưa cài** (macOS) | Tải Docker Desktop: https://www.docker.com/products/docker-desktop/ — script không tự cài được file .dmg |
+| **`permission denied` Docker (Linux)** | Đăng xuất + đăng nhập lại 1 lần (đã thêm bạn vào nhóm `docker`). Kiểm tra: `datn doctor` |
+| **WSL2 chưa có (Windows)** | Chạy lại `install.ps1` sau khi **khởi động lại máy** (script đã chạy `wsl --install`) |
+| **Port bận** (5000/8000/5173/5432/6333/9000) | `datn doctor` báo port + tiến trình. Đóng app chiếm port hoặc dừng stack cũ |
+| **Đĩa đầy khi pull** | Cần ~5GB trống cho images. Dọn ổ rồi `datn up` lại |
+| **Đổi embedding → lỗi dim** | `datn reset` (xoá data) → `datn init` → `datn up`. Đổi dim làm vỡ Qdrant collection |
+| **News/Travel báo "chưa cấu hình"** | Thiếu Tavily/SerpApi key — chạy `datn config tavily` / `datn config serpapi` (optional) |
+| **Image pull lỗi / tag không tồn tại** | Kiểm tra tag trong `~/.datn/provider.lock`; thử `datn update --tag latest` |
+
+## Yêu cầu hệ thống
+- RAM ≥ 4GB (Qdrant + Postgres + backend).
+- Đĩa trống ≥ 5GB (images ~2-4GB).
+- Kết nối Internet (pull images + gọi LLM API).

datn_cli-0.2.2/datn_cli/__init__.py

@@ -0,0 +1,3 @@
+"""datn-cli — one-command distribution wrapper hiding docker compose."""
+
+__version__ = "0.2.2"

datn_cli-0.2.2/datn_cli/__main__.py

@@ -0,0 +1,264 @@
+"""datn — CLI che giấu docker compose cho hệ multi-agent assistant."""
+from __future__ import annotations
+
+import shutil
+import subprocess
+import webbrowser
+
+import typer
+from rich.console import Console
+from rich.prompt import Confirm, Prompt
+
+from . import __version__
+from . import compose as cm
+from . import config as cfg
+from . import doctor as dr
+from . import wizard
+
+console = Console()
+app = typer.Typer(
+    help="datn — one-command distribution (ẩn docker compose).",
+    no_args_is_help=True,
+    add_completion=False,
+)
+config_app = typer.Typer(help="Cấu hình lại sau khi đã chạy.", no_args_is_help=False)
+app.add_typer(config_app, name="config")
+
+
+def _image_tag() -> str:
+    return cfg.read_lock().get("image_tag", cfg.DEFAULT_IMAGE_TAG)
+
+
+# ── init ─────────────────────────────────────────────────────────────────────
+@app.command()
+def init():
+    """Wizard cấu hình LLM + embedding → ghi ~/.datn/.env + provider.lock."""
+    # Nếu đã cấu hình trước đó (re-init), cần biết volumes có tồn tại không để
+    # guard đổi dim hoạt động → đảm bảo Docker chạy. Lần đầu (chưa config) thì
+    # bỏ qua, không bắt user bật Docker chỉ để nhập key.
+    volumes = False
+    if cfg.is_configured():
+        if dr.ensure_docker(auto_start=True):
+            volumes = cm.volumes_exist()
+        else:
+            console.print(
+                "[yellow]⚠ Docker không chạy — bỏ qua kiểm tra volume. "
+                "Nếu đổi embedding dim, hãy chạy `datn reset` thủ công.[/yellow]"
+            )
+    wizard.run_init(image_tag=cfg.DEFAULT_IMAGE_TAG, volumes_exist=volumes)
+
+
+# ── up ───────────────────────────────────────────────────────────────────────
+@app.command()
+def up():
+    """Pull images + khởi động toàn bộ stack + chờ healthy."""
+    if not cfg.is_configured():
+        console.print("[red]Chưa cấu hình. Chạy [bold]datn init[/bold] trước.[/red]")
+        raise typer.Exit(1)
+
+    if not dr.run_doctor(require_config=True):
+        console.print("[red]✗ doctor phát hiện lỗi blocking. Sửa rồi chạy lại.[/red]")
+        raise typer.Exit(1)
+
+    tag = _image_tag()
+    cm.render_compose(tag)
+    try:
+        cm.pull()
+        cm.up()
+    except subprocess.CalledProcessError as e:
+        console.print(
+            f"[bold red]✗ docker compose lỗi (exit {e.returncode}).[/bold red]\n"
+            f"  Xem lỗi docker cụ thể ở ngay phía trên. Nguyên nhân thường gặp:\n"
+            f"    • Port bận (port is already allocated) → đóng app/stack khác chiếm port; chạy [cyan]datn doctor[/cyan]\n"
+            f"    • Image tag '{tag}' chưa có trên Docker Hub / mạng lỗi → kiểm tra [cyan]docker pull {cfg.BACKEND_IMAGE}:{tag}[/cyan]\n"
+            f"    • Container crash → xem [cyan]datn logs[/cyan]"
+        )
+        raise typer.Exit(1)
+    if cm.wait_healthy():
+        console.print(f"\n[bold green]✓ Hệ thống sẵn sàng![/bold green] → {cfg.WEB_URL}")
+        console.print("[dim]Mở bằng: datn open[/dim]")
+    else:
+        console.print("[red]Một số service chưa healthy. Kiểm tra: datn logs[/red]")
+        raise typer.Exit(1)
+
+
+# ── down / open / logs ───────────────────────────────────────────────────────
+@app.command()
+def down():
+    """Dừng stack (giữ data)."""
+    cm.down()
+    console.print("[green]✓ Đã dừng (data được giữ).[/green]")
+
+
+@app.command()
+def open():  # noqa: A001 — tên lệnh user-facing
+    """Mở web UI trên trình duyệt."""
+    console.print(f"→ Mở {cfg.WEB_URL}")
+    webbrowser.open(cfg.WEB_URL)
+
+
+@app.command()
+def logs(service: str = typer.Argument(None, help="Tên service (vd agent-api). Bỏ trống = tất cả.")):
+    """Xem logs realtime."""
+    cm.logs(service)
+
+
+# ── doctor ───────────────────────────────────────────────────────────────────
+@app.command()
+def doctor():
+    """Kiểm tra môi trường (Docker, ports, config, dim...)."""
+    require = cfg.is_configured()
+    ok = dr.run_doctor(require_config=require)
+    raise typer.Exit(0 if ok else 1)
+
+
+# ── reset / update / uninstall ───────────────────────────────────────────────
+@app.command()
+def reset():
+    """Xoá toàn bộ data (volumes) — bắt buộc khi đổi embedding dim."""
+    if not Confirm.ask(
+        "[bold red]Xoá toàn bộ data RAG + chat history?[/bold red]", default=False
+    ):
+        console.print("Đã huỷ.")
+        return
+    cm.reset()
+    console.print("[green]✓ Đã xoá volumes. Chạy datn init + datn up để bắt đầu lại.[/green]")
+
+
+@app.command()
+def update(tag: str = typer.Option(None, "--tag", help="Image tag mới (vd v0.2.0).")):
+    """Đổi image tag → re-render + pull + up lại."""
+    lock = cfg.read_lock()
+    if tag:
+        lock["image_tag"] = tag
+        cfg.write_lock(lock)
+    new_tag = lock.get("image_tag", cfg.DEFAULT_IMAGE_TAG)
+    cm.render_compose(new_tag)
+    try:
+        cm.pull()
+        cm.up()
+    except subprocess.CalledProcessError as e:
+        console.print(f"[bold red]✗ docker compose lỗi (exit {e.returncode}). Tag '{new_tag}' đã push chưa?[/bold red]")
+        raise typer.Exit(1)
+    console.print(f"[green]✓ Đã cập nhật lên tag '{new_tag}'.[/green]")
+
+
+@app.command()
+def uninstall():
+    """down -v + xoá ~/.datn/ (giữ images đã pull)."""
+    if not Confirm.ask(
+        "[bold red]Gỡ datn: xoá data + cấu hình ~/.datn?[/bold red]", default=False
+    ):
+        console.print("Đã huỷ.")
+        return
+    try:
+        cm.reset()
+    except Exception:
+        pass
+    shutil.rmtree(cfg.datn_home(), ignore_errors=True)
+    console.print("[green]✓ Đã gỡ. (Images Docker vẫn còn — xoá tay nếu muốn.)[/green]")
+
+
+@app.command()
+def version():
+    """In version CLI."""
+    console.print(f"datn-cli {__version__}")
+
+
+# ── config sub-app ───────────────────────────────────────────────────────────
+def _after_env_change(restart: bool = True):
+    if restart and dr.docker_ready():
+        cm.restart_backend()
+
+
+@config_app.callback(invoke_without_command=True)
+def config_main(ctx: typer.Context):
+    """Không tham số → menu interactive."""
+    if ctx.invoked_subcommand is not None:
+        return
+    if not cfg.is_configured():
+        console.print("[red]Chưa có config. Chạy [bold]datn init[/bold].[/red]")
+        raise typer.Exit(1)
+    choice = Prompt.ask(
+        "Sửa mục nào?",
+        choices=["llm", "embedding", "tavily", "serpapi"],
+        default="llm",
+    )
+    {"llm": config_llm, "embedding": config_embedding,
+     "tavily": config_tavily, "serpapi": config_serpapi}[choice]()
+
+
+@config_app.command("llm")
+def config_llm():
+    """Đổi LLM provider/model/key → restart backend."""
+    env = cfg.read_env()
+    env.update(wizard.prompt_llm())
+    cfg.write_env(env)
+    lock = cfg.read_lock()
+    lock["llm_provider"] = env["LLM_PROVIDER"]
+    cfg.write_lock(lock)
+    console.print("[green]✓ Đã cập nhật LLM.[/green]")
+    _after_env_change()
+
+
+@config_app.command("embedding")
+def config_embedding():
+    """Đổi embedding → detect dim; nếu đổi dim + có data → bắt reset."""
+    try:
+        new = wizard.prompt_embedding()
+    except wizard.DimensionDetectError as e:
+        console.print(f"[red]✗ {e}[/red]")
+        raise typer.Exit(1)
+
+    lock = cfg.read_lock()
+    old_dim = lock.get("embedding_dim")
+    new_dim = int(new["EMBEDDING_DIM"])
+    if old_dim is not None and old_dim != new_dim and cm.volumes_exist():
+        console.print(
+            f"[bold red]✗ Đổi dim {old_dim}→{new_dim} sẽ vỡ collection. "
+            f"Chạy datn reset trước.[/bold red]"
+        )
+        raise typer.Exit(1)
+
+    env = cfg.read_env()
+    env.update(new)
+    cfg.write_env(env)
+    lock["embedding_provider"] = new["EMBEDDING_PROVIDER"]
+    lock["embedding_dim"] = new_dim
+    cfg.write_lock(lock)
+    console.print("[green]✓ Đã cập nhật embedding.[/green]")
+    _after_env_change()
+
+
+@config_app.command("tavily")
+def config_tavily():
+    """Đổi Tavily API key."""
+    env = cfg.read_env()
+    env["TAVILY_API_KEY"] = Prompt.ask("Tavily API Key", default="", show_default=False)
+    cfg.write_env(env)
+    console.print("[green]✓ Đã cập nhật Tavily.[/green]")
+    _after_env_change()
+
+
+@config_app.command("serpapi")
+def config_serpapi():
+    """Đổi SerpApi API key."""
+    env = cfg.read_env()
+    env["SERPAPI_API_KEY"] = Prompt.ask("SerpApi API Key", default="", show_default=False)
+    cfg.write_env(env)
+    console.print("[green]✓ Đã cập nhật SerpApi.[/green]")
+    _after_env_change()
+
+
+@config_app.command("set")
+def config_set(key: str = typer.Argument(...), value: str = typer.Argument(...)):
+    """Sửa nhanh 1 biến .env (cho người rành env)."""
+    env = cfg.read_env()
+    env[key] = value
+    cfg.write_env(env)
+    console.print(f"[green]✓ {key} = {value}[/green]")
+    _after_env_change()
+
+
+if __name__ == "__main__":
+    app()

datn_cli-0.2.2/datn_cli/compose.py

@@ -0,0 +1,139 @@
+"""Render compose template + bọc các lệnh docker compose."""
+from __future__ import annotations
+
+import platform
+import subprocess
+import time
+from importlib import resources
+
+import httpx
+from jinja2 import Template
+from rich.console import Console
+
+from . import config as cfg
+
+console = Console()
+
+_SYSTEM = platform.system()
+
+
+# ── Render template ──────────────────────────────────────────────────────────
+def _needs_host_gateway() -> bool:
+    """Linux + selfhost URL trỏ host.docker.internal → cần extra_hosts."""
+    if _SYSTEM != "Linux":
+        return False
+    env = cfg.read_env()
+    urls = (env.get("LLM_BASE_URL", ""), env.get("EMBEDDING_BASE_URL", ""))
+    return any("host.docker.internal" in u for u in urls)
+
+
+def render_compose(image_tag: str) -> None:
+    """Render docker-compose.yml vào ~/.datn/ từ template .j2."""
+    tpl_text = (
+        resources.files("datn_cli.templates")
+        .joinpath("docker-compose.dist.yml.j2")
+        .read_text(encoding="utf-8")
+    )
+    rendered = Template(tpl_text).render(
+        backend_image=cfg.BACKEND_IMAGE,
+        frontend_image=cfg.FRONTEND_IMAGE,
+        image_tag=image_tag,
+        env_file=str(cfg.env_path()),
+        needs_host_gateway=_needs_host_gateway(),
+    )
+    cfg.compose_path().write_text(rendered, encoding="utf-8")
+
+
+# ── docker compose wrappers ──────────────────────────────────────────────────
+def _compose(*args: str, check: bool = True, capture: bool = False) -> subprocess.CompletedProcess:
+    # -p datn: pin project name → volume luôn có prefix 'datn_' (deterministic,
+    # không phụ thuộc thư mục chứa compose file). volumes_exist() dựa vào điều này.
+    cmd = ["docker", "compose", "-p", cfg.PROJECT_NAME, "-f", str(cfg.compose_path()), *args]
+    return subprocess.run(cmd, check=check, capture_output=capture, text=True)
+
+
+def volumes_exist() -> bool:
+    """Có volume của project 'datn' nào đang tồn tại không (để guard đổi dim).
+
+    Vì _compose pin -p datn, volume thực tế có dạng 'datn_datn_<name>'. Lọc theo
+    prefix project để không nhầm với volume của dự án khác.
+    """
+    try:
+        r = subprocess.run(
+            ["docker", "volume", "ls", "--format", "{{.Name}}"],
+            capture_output=True, text=True, timeout=10,
+        )
+        prefix = f"{cfg.PROJECT_NAME}_"
+        return any(v.startswith(prefix) for v in r.stdout.split())
+    except Exception:
+        return False
+
+
+def pull() -> None:
+    console.print("[cyan]Pulling images từ Docker Hub...[/cyan]")
+    console.print("[dim]⚠ Lần đầu có thể mất vài phút (~2-4GB).[/dim]")
+    _compose("pull")
+
+
+def up() -> None:
+    console.print("[cyan]Khởi động services...[/cyan]")
+    _compose("up", "-d")
+
+
+def down() -> None:
+    _compose("down")
+
+
+def reset() -> None:
+    """down -v — xoá volumes (mất data RAG + chat history)."""
+    _compose("down", "-v")
+
+
+def logs(service: str | None = None) -> None:
+    args = ["logs", "-f"]
+    if service:
+        args.append(service)
+    _compose(*args, check=False)
+
+
+# ── Health polling ───────────────────────────────────────────────────────────
+def wait_healthy(timeout: int = 120) -> bool:
+    """Poll agent-api `/` + qdrant readiness tới khi healthy hoặc hết giờ."""
+    console.print("[cyan]Chờ services healthy...[/cyan]")
+    # Poll /health (200) — KHÔNG dùng "/" vì api.py không có route đó (trả 404,
+    # sẽ false-positive). /health do api.py expose riêng cho mục đích này.
+    api_url = f"http://localhost:{cfg.PORTS['agent-api']}/health"
+    qdrant_url = f"http://localhost:{cfg.PORTS['qdrant']}/readyz"
+
+    deadline = time.time() + timeout
+    api_ok = qdrant_ok = False
+    while time.time() < deadline:
+        if not qdrant_ok:
+            try:
+                qdrant_ok = httpx.get(qdrant_url, timeout=3).status_code == 200
+                if qdrant_ok:
+                    console.print("[green]✓[/green] qdrant")
+            except Exception:
+                pass
+        if not api_ok:
+            try:
+                api_ok = httpx.get(api_url, timeout=3).status_code == 200
+                if api_ok:
+                    console.print("[green]✓[/green] agent-api")
+            except Exception:
+                pass
+        if api_ok and qdrant_ok:
+            return True
+        time.sleep(3)
+
+    if not qdrant_ok:
+        console.print("[red]✗ qdrant không healthy. Xem: datn logs qdrant[/red]")
+    if not api_ok:
+        console.print("[red]✗ agent-api không healthy. Xem: datn logs agent-api[/red]")
+    return False
+
+
+def restart_backend() -> None:
+    """Restart agent-api + mcp-server để nạp .env mới (không mất data)."""
+    console.print("[cyan]Restart backend để nạp cấu hình mới...[/cyan]")
+    _compose("up", "-d", "--force-recreate", "agent-api", "mcp-server")

datn_cli-0.2.2/datn_cli/config.py

@@ -0,0 +1,137 @@
+"""Đường dẫn + đọc/ghi ~/.datn/.env và provider.lock."""
+from __future__ import annotations
+
+import json
+import os
+import stat
+from pathlib import Path
+
+# Image tag mặc định — phải khớp tag đã push lên Docker Hub (xem notes.md mục C/F).
+DEFAULT_IMAGE_TAG = "latest"
+
+# Compose project name — pin để volume naming deterministic (xem compose.py).
+PROJECT_NAME = "datn"
+
+# Docker Hub images
+BACKEND_IMAGE = "ngoquan0904/datn-backend"
+FRONTEND_IMAGE = "ngoquan0904/datn-frontend"
+
+# Cổng dùng trên host (để doctor kiểm tra + in URL)
+PORTS = {
+    "frontend": 5173,
+    "agent-api": 5000,
+    "mcp-server": 8000,
+    "postgres": 5432,
+    "qdrant": 6333,
+    "minio": 9000,
+    "minio-console": 9001,
+}
+
+WEB_URL = f"http://localhost:{PORTS['frontend']}"
+
+# Field bắt buộc trong .env để hệ thống chạy
+REQUIRED_ENV_FIELDS = [
+    "LLM_PROVIDER",
+    "LLM_MODEL",
+    "EMBEDDING_PROVIDER",
+    "EMBEDDING_MODEL",
+    "EMBEDDING_DIM",
+]
+
+
+def datn_home() -> Path:
+    """Thư mục cấu hình ~/.datn (tạo nếu chưa có)."""
+    home = Path(os.path.expanduser("~")) / ".datn"
+    home.mkdir(parents=True, exist_ok=True)
+    return home
+
+
+def env_path() -> Path:
+    return datn_home() / ".env"
+
+
+def lock_path() -> Path:
+    return datn_home() / "provider.lock"
+
+
+def compose_path() -> Path:
+    return datn_home() / "docker-compose.yml"
+
+
+# ── .env IO ─────────────────────────────────────────────────────────────────
+def read_env() -> dict[str, str]:
+    """Đọc .env thành dict (bỏ qua comment/dòng trống)."""
+    path = env_path()
+    if not path.exists():
+        return {}
+    data: dict[str, str] = {}
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, val = line.partition("=")
+        data[key.strip()] = val.strip()
+    return data
+
+
+def write_env(data: dict[str, str]) -> None:
+    """Ghi .env theo thứ tự khối + chmod 600 (chỉ owner đọc — không lộ key)."""
+    order = [
+        ("# === LLM ===", None),
+        (None, "LLM_PROVIDER"),
+        (None, "LLM_API_KEY"),
+        (None, "LLM_MODEL"),
+        (None, "LLM_BASE_URL"),
+        (None, "LLM_DISABLE_THINKING"),
+        ("# === EMBEDDING ===", None),
+        (None, "EMBEDDING_PROVIDER"),
+        (None, "EMBEDDING_API_KEY"),
+        (None, "EMBEDDING_MODEL"),
+        (None, "EMBEDDING_BASE_URL"),
+        (None, "EMBEDDING_DIM"),
+        # Sub-agent keys (Tavily/SerpApi/Unsplash) KHÔNG ghi mặc định — đã bake trong
+        # image. Chỉ xuất hiện nếu user set tay (datn config set) → vào nhánh "extra".
+    ]
+    lines: list[str] = []
+    written: set[str] = set()
+    for comment, key in order:
+        if comment:
+            if lines:
+                lines.append("")
+            lines.append(comment)
+        elif key is not None:
+            lines.append(f"{key}={data.get(key, '')}")
+            written.add(key)
+    # Giữ lại field lạ (nếu user thêm tay) ở cuối
+    extra = [k for k in data if k not in written]
+    if extra:
+        lines.append("")
+        lines.append("# === Extra ===")
+        for k in extra:
+            lines.append(f"{k}={data[k]}")
+
+    path = env_path()
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    try:
+        path.chmod(stat.S_IRUSR | stat.S_IWUSR)  # 600
+    except OSError:
+        pass  # Windows có thể không hỗ trợ chmod đầy đủ — bỏ qua
+
+
+# ── provider.lock IO ─────────────────────────────────────────────────────────
+def read_lock() -> dict:
+    path = lock_path()
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return {}
+
+
+def write_lock(data: dict) -> None:
+    lock_path().write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+
+def is_configured() -> bool:
+    return env_path().exists()