diff --git a/.dockerignore b/.dockerignore
index 9ddb329..f79a8ab 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -11,7 +11,8 @@ venv
htmlcov
.env
.env.*
-*.env
+!.env.example
+!.env.docker.example
.streamlit/secrets.toml
data
*.db
diff --git a/config/docker.env.example b/.env.docker.example
similarity index 86%
rename from config/docker.env.example
rename to .env.docker.example
index 39611aa..610842d 100644
--- a/config/docker.env.example
+++ b/.env.docker.example
@@ -7,8 +7,6 @@ APP_PORT=8501
# Host Ollama on Windows: http://host.docker.internal:11434
# Docker Ollama (--profile local-ai): http://ollama:11434
OLLAMA_BASE_URL=http://host.docker.internal:11434
-# Must match a model already installed in Ollama.
-OLLAMA_MODEL=qwen2.5:1.5b
GEMINI_API_KEY=
GROQ_API_KEY=
CEREBRAS_API_KEY=
diff --git a/config/local.env.example b/.env.example
similarity index 89%
rename from config/local.env.example
rename to .env.example
index 97d8a4c..c971628 100644
--- a/config/local.env.example
+++ b/.env.example
@@ -1,7 +1,6 @@
# Optional provider keys. Never commit the real .env file.
DATABASE_URL=sqlite:///data/app.db
OLLAMA_BASE_URL=http://localhost:11434
-OLLAMA_MODEL=qwen2.5:1.5b
GEMINI_API_KEY=
GROQ_API_KEY=
CEREBRAS_API_KEY=
diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml
index d00696c..749dbbc 100644
--- a/.github/workflows/quality.yml
+++ b/.github/workflows/quality.yml
@@ -2,7 +2,7 @@ name: quality
on:
push:
- branches: [main, develop, 'feature/**', 'fix/**', 'refactor/**', 'chore/**', 'ci/**']
+ branches: [main, 'feature/**', 'fix/**', 'refactor/**', 'chore/**', 'ci/**']
pull_request:
permissions:
@@ -22,8 +22,8 @@ jobs:
with:
python-version: '3.11'
cache: pip
- cache-dependency-path: requirements/dev.txt
- - run: python -m pip install -r requirements/dev.txt
+ cache-dependency-path: requirements-dev.txt
+ - run: python -m pip install -r requirements-dev.txt
- run: python -m pip install --no-build-isolation --no-deps -e ./backend
- run: ruff check .
- run: ruff format --check .
@@ -45,22 +45,22 @@ jobs:
env:
POSTGRES_USER: fixture
POSTGRES_PASSWORD: fixture-test-only
- POSTGRES_DB: study_test
+ POSTGRES_DB: p0_test
ports: ['5432:5432']
options: >-
- --health-cmd "pg_isready -U fixture -d study_test"
+ --health-cmd "pg_isready -U fixture -d p0_test"
--health-interval 5s --health-timeout 5s --health-retries 20
env:
- DATABASE_URL: postgresql+psycopg2://fixture:fixture-test-only@localhost:5432/study_test
- STUDY_TEST_DATABASE_URL: postgresql+psycopg2://fixture:fixture-test-only@localhost:5432/study_test
+ DATABASE_URL: postgresql+psycopg2://fixture:fixture-test-only@localhost:5432/p0_test
+ P0_TEST_DATABASE_URL: postgresql+psycopg2://fixture:fixture-test-only@localhost:5432/p0_test
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.11'
cache: pip
- cache-dependency-path: requirements/dev.txt
- - run: python -m pip install -r requirements/dev.txt
+ cache-dependency-path: requirements-dev.txt
+ - run: python -m pip install -r requirements-dev.txt
- run: python -m pip install --no-build-isolation --no-deps -e ./backend
- run: python -m alembic -c backend/alembic.ini upgrade head
- run: python -m alembic -c backend/alembic.ini check
@@ -81,7 +81,7 @@ jobs:
cache-to: type=gha,mode=max
- name: Compose and functional smoke without models
run: |
- cp config/docker.env.example .env.docker
+ cp .env.docker.example .env.docker
docker compose --env-file .env.docker config --quiet
docker compose --env-file .env.docker up -d --no-build --wait
curl --fail http://localhost:8501/_stcore/health
diff --git a/.gitignore b/.gitignore
index 00730ec..c2df83d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -39,9 +39,6 @@ _venv/
# Tuyệt đối không đẩy file chứa API Keys lên Git
.env
.env.local
-.env.*
-*.env
-!*.env.example
secrets.toml
config.ini
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c078053..92808df 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,16 +1,19 @@
# Contributing
-Branch from the latest `origin/develop`, use conventional commits and review each
-vertical slice separately. Local refactor checkpoints are a dependency stack;
-submit/rebase them in plan order after preceding slices merge into develop.
-No direct main push or release tag is part of consolidation. Do not commit secrets,
-student PDFs, database dumps or model weights.
+Keep PRs small and reversible. Branch from the current foundation branch until it
+is merged, then from main. Use conventional commits (`fix`, `refactor`, `infra`,
+`ci`, `docs`); each correctness change needs a reproducing test. No direct main pushes
+or v1 tags in Phase 0. Never include `.env`, real uploaded PDFs, model weights or keys.
-PowerShell offline gates from repository root:
+Maintainer should configure branch protection for main: require review and the
+`quality` workflow's offline/postgres/docker jobs. This document does not configure
+GitHub protection settings; remote enforcement must be verified separately.
+
+PowerShell setup:
```powershell
python -m venv .venv
-.venv/Scripts/python -m pip install -r requirements/dev.txt
+.venv/Scripts/python -m pip install -r requirements-dev.txt
.venv/Scripts/python -m pip install --no-build-isolation --no-deps -e ./backend
.venv/Scripts/python -m pytest -q
.venv/Scripts/ruff check .
@@ -19,19 +22,23 @@ python -m venv .venv
.venv/Scripts/python -m build --no-isolation ./backend
```
-POSIX substitutes `.venv/bin/`. Supported Python is 3.11–3.12. Default tests use
-fakes and never download weights or call cloud providers. Ruff covers canonical
-code, apps, migrations, scripts, evaluation and all tests. Public contracts/ports
-use explicit types; the architecture gate limits vendor imports to reviewed,
-deterministic modules and prohibits SDK/network imports in pure layers.
-
-PostgreSQL integration requires a disposable migrated DB: set `DATABASE_URL` and
-`STUDY_TEST_DATABASE_URL`, run Alembic upgrade/check, then
-`python -m pytest backend/tests/integration -q`. Missing configuration fails this
-suite. Tests add/delete fixture records, so never use retained user data.
-
-Use [Docker smoke/backup commands](docs/operations/docker.md) for runtime changes.
-Real-model smoke and [evaluation](evaluation/README.md) are opt-in. Record local
-results separately from remote CI and human browser acceptance. Review and the
-quality workflow's offline/postgres/docker checks should protect develop/main;
-the repository files do not configure GitHub branch protection automatically.
+POSIX: replace `.venv/Scripts/python` with `.venv/bin/python` and
+`.venv/Scripts/ruff` with `.venv/bin/ruff`. Python 3.11–3.12 is supported.
+Run from repository root. Dev lock provides offline test dependencies; it does not
+install Torch/Chroma or download weights. Docker supplies the complete CPU runtime.
+Root pytest explicitly selects offline suites; online evaluation scripts are opt-in.
+
+Ruff applies to P0 new/touched code; untouched legacy modules will be brought into
+the gate as they are extracted in P1. Current typing policy: annotate new contracts,
+ports and public core functions, validate DTOs at runtime; static type checking is
+deferred until legacy adapters have typed boundaries.
+
+PostgreSQL integration: create a disposable database, set both DATABASE_URL and
+P0_TEST_DATABASE_URL, run Alembic upgrade/check, then
+`python -m pytest backend/tests/integration -q`. Missing DB configuration fails this
+suite explicitly. Never point it at retained user data.
+
+Full embedding/Ollama/browser smoke is a separate acceptance check with recorded
+model/environment metadata. Fast CI must not call cloud LLMs or require GPU access.
+See [Docker](docs/operations/docker.md), [migrations](docs/operations/migrations.md)
+and [acceptance evidence](docs/reports/p0-acceptance.md).
diff --git a/Dockerfile b/Dockerfile
index 0dcd3c1..ac53673 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -9,9 +9,9 @@ WORKDIR /app
RUN apt-get update \
&& apt-get install --no-install-recommends -y libgomp1 \
&& rm -rf /var/lib/apt/lists/*
-COPY requirements/runtime.txt ./requirements/runtime.txt
+COPY requirements.txt ./
RUN python -m pip install --upgrade pip \
- && python -m pip install -r requirements/runtime.txt
+ && python -m pip install -r requirements.txt
RUN useradd --uid 10001 --create-home --shell /usr/sbin/nologin study \
&& mkdir -p /app/data /home/study/.cache/huggingface \
&& chown -R study:study /app/data /home/study
diff --git a/README.md b/README.md
index 26f277d..90c65fc 100644
--- a/README.md
+++ b/README.md
@@ -1,28 +1,41 @@
# Self Study Supporter
-Ứng dụng tự học từ PDF: đăng ký/đăng nhập, BGE-M3 semantic chunking, hybrid
-Dense/BM25/RRF, ReAct chat kèm nguồn, quiz/progress và concept graph.
-Code nghiệp vụ nằm trong `backend/src/study_supporter`; Streamlit ở
-`apps/streamlit_legacy` gọi application services qua bootstrap.
+Ứng dụng hỗ trợ tự học từ PDF, hiện dùng Streamlit, PostgreSQL/SQLite và Chroma.
+Nhánh `feature/docker-local-foundation` xây dựng nền tảng kỹ thuật Phase 0.
-Chạy Docker từ repository root (PowerShell):
+Đã triển khai: đăng ký/đăng nhập; PDF có text layer; semantic chunking với BGE-M3;
+hybrid retrieval Dense + BM25 + RRF; custom ReAct với công cụ tìm tài liệu, quiz,
+ghi chú và tiến độ; concept graph/lộ trình học; quiz lưu SQL; persistent Chroma.
+Quiz chỉ được chấm khi có đúng bốn lựa chọn và một đáp án hợp lệ. PDF scan cần OCR.
+
+Next.js, FastAPI, LangGraph, reranker và cá nhân hóa mastery thuộc roadmap, chưa
+triển khai trong Phase 0. Chưa phát hành v1.0.0; chưa có benchmark chất lượng LLM.
+
+## Chạy bằng Docker (PowerShell)
```powershell
-Copy-Item config/docker.env.example .env.docker
-# Đặt POSTGRES_PASSWORD; cấu hình Ollama hoặc provider nếu cần chat/quiz.
+git clone https://github.com/ManhT005/self-study_supporter.git
+cd self-study_supporter
+git switch feature/docker-local-foundation
+Copy-Item .env.docker.example .env.docker
+# Đổi POSTGRES_PASSWORD. Có thể để trống các key cloud.
docker compose --env-file .env.docker config --quiet
docker compose --env-file .env.docker up -d --build --wait
```
-Mở http://localhost:8501. Docker chạy migration trước app và giữ SQL/Chroma/model
-cache trong volume. BGE-M3 tải khi ingest lần đầu; chat/quiz cần model đã có ở
-Ollama hoặc cloud provider. PDF scan cần OCR; quiz phải có bốn lựa chọn hợp lệ.
+Mở http://localhost:8501. Docker dùng Python 3.11/CPU và chạy migration trước app.
+App khỏe không đồng nghĩa model đã sẵn sàng. BGE-M3 tải vào `hf_cache` khi ingest;
+chat/quiz cần Ollama đã có model hoặc provider được cấu hình. Không tải model khi build.
+Đọc [Docker/Ollama/backup](docs/operations/docker.md) trước khi thao tác dữ liệu.
+POSIX dùng `cp` thay `Copy-Item`; các lệnh Compose giống nhau.
+
+## Kiểm thử và phát triển
-Phát triển/test offline, Python 3.11–3.12:
+Python 3.11–3.12; dùng môi trường riêng. Bộ test nhanh không gọi model hoặc cloud.
```powershell
python -m venv .venv
-.venv/Scripts/python -m pip install -r requirements/dev.txt
+.venv/Scripts/python -m pip install -r requirements-dev.txt
.venv/Scripts/python -m pip install --no-build-isolation --no-deps -e ./backend
.venv/Scripts/python -m pytest -q
.venv/Scripts/ruff check .
@@ -30,18 +43,18 @@ python -m venv .venv
.venv/Scripts/python scripts/check_import_boundaries.py
```
-POSIX dùng `.venv/bin/`. Native UI cần runtime dependencies và migration; xem
-[env mẫu](config/README.md) và [dependency locks](requirements/README.md).
-`main.py` và `eval_test.py` là command redirects để giữ lệnh cũ hoạt động.
+`backend/` là distribution `study-supporter` theo src-layout, không có runtime
+framework dependency. Legacy `src/` và `ui/` được giữ lại; RRF forward sang package
+mới và có golden tests. Không đổi thuật toán, model, vector dimension hoặc ID collection.
+Các nhóm import được kiểm tra bằng AST; core không import UI, driver hoặc SDK.
-- [Kiến trúc](docs/architecture/overview.md) và [ADR consolidation](docs/architecture/adr/repository-consolidation.md)
-- [Đóng góp và command matrix](CONTRIBUTING.md)
-- [Docker/Ollama/backup](docs/operations/docker.md) và [migrations](docs/operations/migrations.md)
-- [Kết quả refactor](docs/reports/repository-consolidation-acceptance.md)
-- [Evaluation opt-in](evaluation/README.md)
+- [Hướng dẫn đóng góp và command matrix](CONTRIBUTING.md)
+- [Kiến trúc và ADR](docs/architecture/overview.md)
+- [Kế hoạch Phase 0](docs/plans/PHASE_0_ENGINEERING_FOUNDATION.md)
+- [Migration DB trống và adoption DB cũ](docs/operations/migrations.md)
- [Contract cho frontend tương lai](docs/api/README.md)
-- [Kế hoạch foundation lịch sử](docs/plans/PHASE_0_ENGINEERING_FOUNDATION.md) và [bằng chứng cũ](docs/reports/p0-acceptance.md)
+- [Kết quả nghiệm thu thực tế và phần còn thiếu](docs/reports/p0-acceptance.md)
-Không commit env thật, PDF người dùng, dumps hoặc model weights. `down`/`up` giữ
-volume; tránh `down -v` với dữ liệu cần giữ. Next.js/FastAPI/LangGraph và thay đổi
-retrieval thuộc workstream riêng; consolidation không thay schema/model/vector IDs.
+Không commit `.env`, tài liệu người dùng, Chroma/SQL dumps hay model weights.
+Dùng `down`/`up` để giữ volume; không dùng `down -v` với dữ liệu cần giữ.
+DB cũ chưa có revision Alembic cần backup, schema comparison và review trước adoption.
diff --git a/docs/ai-study-agent.md b/ai-study-agent.md
similarity index 99%
rename from docs/ai-study-agent.md
rename to ai-study-agent.md
index ea212fb..3fcfff3 100644
--- a/docs/ai-study-agent.md
+++ b/ai-study-agent.md
@@ -1,5 +1,3 @@
-> Historical project proposal. Current layout and commands: [README](../README.md) and [architecture](architecture/overview.md).
-
# TÀI LIỆU THIẾT KẾ & KẾ HOẠCH TRIỂN KHAI DỰ ÁN: AI STUDY AGENT
**Vị trí định hướng:** AI Agent & Algorithm (Chương trình Sinh viên Công nghệ Tập sự)
diff --git a/apps/streamlit_legacy/components/chat.py b/apps/streamlit_legacy/components/chat.py
index ac7722e..0d96e07 100644
--- a/apps/streamlit_legacy/components/chat.py
+++ b/apps/streamlit_legacy/components/chat.py
@@ -18,7 +18,6 @@ def render_chat():
for msg in st.session_state.chat_history:
with st.chat_message(msg["role"]):
st.markdown(msg["content"])
- _render_sources(msg.get("evidences", ()))
else:
st.markdown("_Nhập câu hỏi để bắt đầu cuộc hội thoại._")
@@ -65,18 +64,17 @@ def _handle_message(user_question: str) -> None:
return
st.markdown(result.answer)
- _render_sources(result.evidences)
+ evidence = result.evidences
+ sources = [
+ f"{item.source} · trang {item.page_start}-{item.page_end} · {item.chunk_id}"
+ for item in evidence
+ ]
+ chip_html = "".join(
+ f"{html.escape(source)}" for source in sources
+ )
+ st.markdown(
+ f"
{chip_html}
",
+ unsafe_allow_html=True,
+ )
- st.session_state.chat_history.append(
- {"role": "assistant", "content": result.answer, "evidences": result.evidences}
- )
-
-
-def _render_sources(evidences):
- sources = [
- f"{item.source} · trang {item.page_start}-{item.page_end} · {item.chunk_id}"
- for item in evidences
- ]
- if sources:
- chips = "".join(f"{html.escape(source)}" for source in sources)
- st.markdown(f"{chips}
", unsafe_allow_html=True)
+ st.session_state.chat_history.append({"role": "assistant", "content": result.answer})
diff --git a/backend/README.md b/backend/README.md
index 6311278..962bcc0 100644
--- a/backend/README.md
+++ b/backend/README.md
@@ -1,7 +1,6 @@
# study-supporter
Python 3.11–3.12, src layout. Install with `python -m pip install -e ./backend`.
-Core installs only deterministic NumPy/Pydantic/NetworkX dependencies. Runtime
-drivers are in the runtime extra; Streamlit lives in apps/streamlit_legacy.
+Core has no runtime dependencies. Legacy adapters forward to unchanged pure RRF.
Contracts require authenticated identity; ownership is checked before retrieval.
Run `python scripts/check_import_boundaries.py` and `python -m pytest` from repo root.
diff --git a/backend/migrations/env.py b/backend/migrations/env.py
index cb0018e..1d8d013 100644
--- a/backend/migrations/env.py
+++ b/backend/migrations/env.py
@@ -1,29 +1,23 @@
-"""Explicit migration lifecycle; never load dotenv or print credentials."""
+"""Explicit migrations; do not load .env or print connection URLs."""
-import os
from alembic import context
-from study_supporter.config import Settings
-from study_supporter.infrastructure.persistence.sqlalchemy.database import Base, Database
-from study_supporter.infrastructure.persistence.sqlalchemy import models # noqa: F401
+
+from src.db.database import Base, engine
+from src.db import models # noqa: F401: register models for metadata comparison
target_metadata = Base.metadata
-database = Database(Settings.from_mapping(os.environ))
-try:
- if context.is_offline_mode():
- context.configure(
- url=database.engine.url,
- target_metadata=target_metadata,
- literal_binds=True,
- dialect_opts={"paramstyle": "named"},
- )
+
+if context.is_offline_mode():
+ context.configure(
+ url=engine.url,
+ target_metadata=target_metadata,
+ literal_binds=True,
+ dialect_opts={"paramstyle": "named"},
+ )
+ with context.begin_transaction():
+ context.run_migrations()
+else:
+ with engine.connect() as connection:
+ context.configure(connection=connection, target_metadata=target_metadata, compare_type=True)
with context.begin_transaction():
context.run_migrations()
- else:
- with database.engine.connect() as connection:
- context.configure(
- connection=connection, target_metadata=target_metadata, compare_type=True
- )
- with context.begin_transaction():
- context.run_migrations()
-finally:
- database.close()
diff --git a/backend/pyproject.toml b/backend/pyproject.toml
index 31b91a5..4e621a4 100644
--- a/backend/pyproject.toml
+++ b/backend/pyproject.toml
@@ -7,11 +7,10 @@ name = "study-supporter"
version = "0.0.0"
description = "Framework-independent core of Self Study Supporter"
requires-python = ">=3.11,<3.13"
-dependencies = ["numpy==1.26.4", "pydantic==2.10.4", "networkx==3.4.2"]
+dependencies = []
[project.optional-dependencies]
-dev = ['pytest==8.3.4', 'ruff==0.9.10', 'build==1.2.2.post1', 'setuptools==75.6.0', 'wheel==0.45.1', 'requests==2.32.5', 'sqlalchemy==2.0.36', 'streamlit==1.41.1', 'pymupdf==1.25.1', 'python-dotenv==1.0.1', 'bcrypt==4.2.1', 'alembic==1.14.0', 'psycopg2-binary==2.9.10', 'google-genai==1.56.0', 'rank-bm25==0.2.2']
-runtime = ['google-genai==1.56.0', 'python-dotenv==1.0.1', 'pymupdf==1.25.1', 'chromadb==0.5.23', 'posthog==3.7.0', 'rank-bm25==0.2.2', 'sentence-transformers==3.3.1', 'transformers==4.46.3', 'torch==2.5.1', 'sqlalchemy==2.0.36', 'streamlit==1.41.1', 'requests==2.32.5', 'bcrypt==4.2.1', 'psycopg2-binary==2.9.10', 'alembic==1.14.0']
+dev = ["pytest==8.3.4", "ruff==0.9.10", "build==1.2.2.post1"]
[tool.setuptools.packages.find]
where = ["src"]
diff --git a/backend/src/study_supporter/application/use_cases/answer_question.py b/backend/src/study_supporter/application/use_cases/answer_question.py
index 168f650..1c9d1ac 100644
--- a/backend/src/study_supporter/application/use_cases/answer_question.py
+++ b/backend/src/study_supporter/application/use_cases/answer_question.py
@@ -1,6 +1,5 @@
import uuid
from study_supporter.application.contracts.learning import AnswerResult
-from study_supporter.domain.errors import EvidenceNotFound
class AnswerQuestionUseCase:
@@ -8,8 +7,6 @@ def __init__(self, runner, evidence_tool):
self.runner, self.evidence_tool = runner, evidence_tool
def execute(self, request):
- if request.context != self.evidence_tool.context:
- raise EvidenceNotFound("Document not found")
self.evidence_tool.last_evidence = []
state = self.runner.run(request.question)
return AnswerResult(
diff --git a/backend/src/study_supporter/application/use_cases/session.py b/backend/src/study_supporter/application/use_cases/session.py
index 7c818d3..fc8c536 100644
--- a/backend/src/study_supporter/application/use_cases/session.py
+++ b/backend/src/study_supporter/application/use_cases/session.py
@@ -20,14 +20,12 @@ def __init__(
progress,
documents,
llm,
- notes=None,
mode="auto",
notice="",
):
self.context, self.document, self.chunks = context, document, tuple(chunks)
self._answer, self._generator, self._submit = answer, generator, submit
self._progress, self._documents, self._llm = progress, documents, llm
- self._notes = notes
self.mode, self.notice = mode, notice
self.graph = (
ConceptGraph(**document["concept_graph_json"])
@@ -67,9 +65,6 @@ def submit_quiz(self, question, selected):
def progress(self):
return self._progress.execute(self.context)
- def save_note(self, note):
- return self._notes.execute(self.context, note)
-
def build_graph(self):
self._documents.get(self.context.user_id, self.document["id"])
self.graph = build_concept_graph(
diff --git a/backend/src/study_supporter/bootstrap.py b/backend/src/study_supporter/bootstrap.py
index 4b38f8e..fca915d 100644
--- a/backend/src/study_supporter/bootstrap.py
+++ b/backend/src/study_supporter/bootstrap.py
@@ -1,4 +1,4 @@
-"""Explicit application composition and process resource lifecycle."""
+"""Explicit core composition; legacy infrastructure is wired by the UI adapter."""
from threading import RLock
@@ -44,10 +44,9 @@ def embed(self, texts, task_type):
class ApplicationFactory:
"""Process resources only. Account-bound tools are created for each session later."""
- def __init__(self, settings: Settings, *, embedding=None, provider_factory=None):
+ def __init__(self, settings: Settings):
self.settings = settings
- self.embedding = embedding if embedding is not None else SharedEmbedding(settings)
- self._provider_factory = provider_factory
+ self.embedding = SharedEmbedding(settings)
from study_supporter.infrastructure.persistence.sqlalchemy.database import Database
from study_supporter.infrastructure.persistence.sqlalchemy.repositories import (
DocumentRepository,
@@ -78,12 +77,7 @@ def __init__(self, settings: Settings, *, embedding=None, provider_factory=None)
def vector_store(self, document):
from study_supporter.infrastructure.persistence.chroma.vector_store import VectorStore
- return VectorStore(
- self.settings.chroma_path,
- document["chroma_collection_name"],
- host=self.settings.chroma_host,
- port=self.settings.chroma_port,
- )
+ return VectorStore(self.settings.chroma_path, document["chroma_collection_name"])
def retriever(self):
from study_supporter.infrastructure.retrieval.scoped_retriever import ScopedHybridRetriever
@@ -110,7 +104,7 @@ def __exit__(self, *args):
def provider(self, mode="auto"):
from study_supporter.infrastructure.llm.factory import select_provider
- return (self._provider_factory or select_provider)(self.settings, mode)
+ return select_provider(self.settings, mode)
def open_document(self, context, document_id=None, mode="auto"):
from study_supporter.application.contracts.context import AppContext
@@ -166,7 +160,6 @@ def open_document(self, context, document_id=None, mode="auto"):
progress,
self.document_repository,
selection.client,
- notes=notes,
mode=selection.mode,
notice=selection.notice,
)
diff --git a/backend/src/study_supporter/infrastructure/llm/json_utils.py b/backend/src/study_supporter/infrastructure/llm/json_utils.py
new file mode 100644
index 0000000..66a46f2
--- /dev/null
+++ b/backend/src/study_supporter/infrastructure/llm/json_utils.py
@@ -0,0 +1,4 @@
+from study_supporter.ai.assessment.json_parsing import * # noqa: F403
+from study_supporter.application.use_cases.llm_json import (
+ chat_and_parse_model as chat_and_parse_model,
+)
diff --git a/backend/src/study_supporter/infrastructure/persistence/chroma/vector_store.py b/backend/src/study_supporter/infrastructure/persistence/chroma/vector_store.py
index a82d199..10ca4d5 100644
--- a/backend/src/study_supporter/infrastructure/persistence/chroma/vector_store.py
+++ b/backend/src/study_supporter/infrastructure/persistence/chroma/vector_store.py
@@ -4,14 +4,7 @@
class VectorStore:
- def __init__(
- self,
- persist_path: str = "data/chroma_db",
- collection_name: str = "documents",
- *,
- host: str | None = None,
- port: int | None = None,
- ):
+ def __init__(self, persist_path: str = "data/chroma_db", collection_name: str = "documents"):
"""
collection_name: do caller quyết định (ví dụ f"documents_{document_id}")
— mỗi tài liệu 1 collection riêng, cách ly hoàn toàn giữa các tài liệu/user,
@@ -26,9 +19,9 @@ def __init__(
self.persist_path = persist_path
- chroma_host = host if host is not None else os.getenv("CHROMA_SERVER_HOST")
+ chroma_host = os.getenv("CHROMA_SERVER_HOST")
if chroma_host:
- chroma_port = port if port is not None else int(os.getenv("CHROMA_SERVER_PORT", "8000"))
+ chroma_port = int(os.getenv("CHROMA_SERVER_PORT", "8000"))
self.client = chromadb.HttpClient(
host=chroma_host, port=chroma_port, settings=Settings(anonymized_telemetry=False)
)
diff --git a/backend/src/study_supporter/infrastructure/retrieval/legacy_tools.py b/backend/src/study_supporter/infrastructure/retrieval/legacy_tools.py
new file mode 100644
index 0000000..83521d3
--- /dev/null
+++ b/backend/src/study_supporter/infrastructure/retrieval/legacy_tools.py
@@ -0,0 +1,64 @@
+from study_supporter.application.ports.tool import BaseTool
+from study_supporter.infrastructure.retrieval.hybrid_adapter import hybrid_search
+from study_supporter.application.contracts.retrieval import Evidence
+
+
+class SearchDocsTool(BaseTool):
+ name = "search_docs"
+ description = "Tìm kiếm thông tin liên quan trong tài liệu học tập đã upload."
+ param_descriptions = {
+ "query": "Câu hỏi hoặc từ khóa cần tìm kiếm trong tài liệu",
+ "top_k": "Số lượng đoạn văn bản liên quan cần trả về (mặc định 3)",
+ }
+
+ def __init__(self, vector_store, bm25_index, embed_query_fn, document_id: str | None = None):
+ self.vector_store = vector_store
+ self.bm25_index = bm25_index
+ self.embed_query_fn = embed_query_fn
+ self.document_id = document_id
+ self.last_evidence: list[Evidence] = []
+
+ def run(self, query: str, top_k: int = 3) -> str:
+ self.last_evidence = []
+ query = query.strip()
+ if not query:
+ return "Lỗi: câu truy vấn rỗng, không thể tìm kiếm."
+
+ chunks = hybrid_search(
+ query=query,
+ vector_store=self.vector_store,
+ bm25_index=self.bm25_index,
+ embed_query_fn=self.embed_query_fn,
+ top_k=top_k,
+ )
+
+ if not chunks:
+ return "Không tìm thấy thông tin liên quan trong tài liệu."
+
+ results = []
+ for chunk in chunks:
+ if (
+ self.document_id
+ and chunk.chunk_id
+ and chunk.source
+ and chunk.page_start
+ and chunk.page_end
+ ):
+ self.last_evidence.append(
+ Evidence(
+ chunk.chunk_id,
+ self.document_id,
+ chunk.text,
+ chunk.source,
+ chunk.page_start,
+ chunk.page_end,
+ )
+ )
+ page = (
+ f"trang {chunk.page_start}"
+ if chunk.page_start == chunk.page_end
+ else f"trang {chunk.page_start}-{chunk.page_end}"
+ )
+ results.append(f"[Nguồn: {chunk.source}, {page}]\n{chunk.text}")
+
+ return "\n\n".join(results)
diff --git a/backend/src/study_supporter/orchestration/legacy_react/orchestrator.py b/backend/src/study_supporter/orchestration/legacy_react/orchestrator.py
index e938be7..55dd4a6 100644
--- a/backend/src/study_supporter/orchestration/legacy_react/orchestrator.py
+++ b/backend/src/study_supporter/orchestration/legacy_react/orchestrator.py
@@ -37,7 +37,7 @@ def __init__(self, llm: LLMAdapter, tools: list[BaseTool]):
self.system_prompt = build_react_system_prompt(tools)
def parse_llm_output(self, text: str) -> dict:
- r"""
+ """
text
│
diff --git a/backend/src/study_supporter/orchestration/legacy_react/tools/get_progress.py b/backend/src/study_supporter/orchestration/legacy_react/tools/get_progress.py
index 10eb0dc..2d0c95c 100644
--- a/backend/src/study_supporter/orchestration/legacy_react/tools/get_progress.py
+++ b/backend/src/study_supporter/orchestration/legacy_react/tools/get_progress.py
@@ -13,7 +13,11 @@ def __init__(self, progress_db: GetProgressUseCase, user_id: str):
self.user_id = user_id
def run(self) -> str:
- summary = self.progress_db.execute(AppContext(self.user_id))
+ summary = (
+ self.progress_db.execute(AppContext(self.user_id))
+ if hasattr(self.progress_db, "execute")
+ else self.progress_db.get_summary(self.user_id)
+ )
if summary["total_attempts"] == 0:
return f"Học sinh '{self.user_id}' chưa làm quiz nào."
diff --git a/backend/src/study_supporter/orchestration/legacy_react/tools/save_note.py b/backend/src/study_supporter/orchestration/legacy_react/tools/save_note.py
index 7e6afb2..c4bfd74 100644
--- a/backend/src/study_supporter/orchestration/legacy_react/tools/save_note.py
+++ b/backend/src/study_supporter/orchestration/legacy_react/tools/save_note.py
@@ -15,5 +15,9 @@ def __init__(self, long_term_memory: SaveNoteUseCase, user_id: str):
self.user_id = user_id
def run(self, note: str) -> str:
- note_id = self.long_term_memory.execute(AppContext(self.user_id), note)
+ note_id = (
+ self.long_term_memory.execute(AppContext(self.user_id), note)
+ if hasattr(self.long_term_memory, "execute")
+ else self.long_term_memory.save_note(self.user_id, note)
+ )
return f"Đã lưu ghi chú (id: {note_id}) cho học sinh '{self.user_id}': {note}"
diff --git a/evaluation/__init__.py b/backend/src/study_supporter/orchestration/legacy_react/tools/search_docs.py
similarity index 100%
rename from evaluation/__init__.py
rename to backend/src/study_supporter/orchestration/legacy_react/tools/search_docs.py
diff --git a/backend/tests/contract/test_canonical_entrypoints.py b/backend/tests/contract/test_canonical_entrypoints.py
deleted file mode 100644
index 869e865..0000000
--- a/backend/tests/contract/test_canonical_entrypoints.py
+++ /dev/null
@@ -1,21 +0,0 @@
-"""All executable callers must use the installed distribution after shim removal."""
-
-import ast
-from pathlib import Path
-
-
-def test_no_legacy_namespace_in_entrypoints_or_helpers():
- root = Path(__file__).resolve().parents[3]
- sources = [root / "main.py", root / "eval_test.py", root / "backend/migrations/env.py"]
- for directory in ["apps", "scripts", "evaluation", "backend/tests"]:
- sources.extend((root / directory).rglob("*.py"))
- for path in sources:
- for node in ast.walk(ast.parse(path.read_text(encoding="utf-8"))):
- imports = (
- [alias.name for alias in node.names]
- if isinstance(node, ast.Import)
- else [node.module or ""]
- if isinstance(node, ast.ImportFrom)
- else []
- )
- assert all(name.split(".")[0] not in {"src", "ui"} for name in imports), path
diff --git a/backend/tests/contract/test_presentation_boundaries.py b/backend/tests/contract/test_presentation_boundaries.py
index bc4c5a6..cbcdd51 100644
--- a/backend/tests/contract/test_presentation_boundaries.py
+++ b/backend/tests/contract/test_presentation_boundaries.py
@@ -6,22 +6,10 @@ def test_components_do_not_import_storage_provider_or_algorithm_implementations(
root = Path(__file__).resolve().parents[3] / "apps/streamlit_legacy/components"
for path in root.glob("*.py"):
for node in ast.walk(ast.parse(path.read_text(encoding="utf-8"))):
- modules = (
- [alias.name for alias in node.names]
- if isinstance(node, ast.Import)
- else [node.module or ""]
- if isinstance(node, ast.ImportFrom)
- else []
- )
- for module in modules:
+ if isinstance(node, ast.ImportFrom):
+ module = node.module or ""
assert not module.startswith(
- (
- "src",
- "ui",
- "study_supporter.infrastructure",
- "study_supporter.orchestration",
- "study_supporter.ai",
- )
+ ("src", "study_supporter.infrastructure", "study_supporter.orchestration")
), (path, module)
diff --git a/backend/tests/integration/test_postgres_baseline.py b/backend/tests/integration/test_postgres_baseline.py
index 5d4af11..711c75f 100644
--- a/backend/tests/integration/test_postgres_baseline.py
+++ b/backend/tests/integration/test_postgres_baseline.py
@@ -1,4 +1,4 @@
-"""Requires a disposable migrated PostgreSQL DB in STUDY_TEST_DATABASE_URL."""
+"""Requires a disposable migrated PostgreSQL DB in P0_TEST_DATABASE_URL."""
import os
import uuid
@@ -9,18 +9,18 @@
from sqlalchemy import create_engine, inspect, text
from sqlalchemy.orm import sessionmaker
-from study_supporter.infrastructure.persistence.sqlalchemy.database import Base
-from study_supporter.infrastructure.persistence.sqlalchemy.models import User
-from study_supporter.infrastructure.persistence.sqlalchemy import document_repository as documents
-from study_supporter.infrastructure.persistence.sqlalchemy.progress_repository import ProgressDB
+from src.db.database import Base
+from src.db.models import User
+from src.documents import document_service as documents
+from src.memory.progress_db import ProgressDB
from study_supporter.domain.errors import EvidenceNotFound
@pytest.fixture
def pg_repository(monkeypatch):
- url = os.environ.get("STUDY_TEST_DATABASE_URL")
+ url = os.environ.get("P0_TEST_DATABASE_URL")
if not url:
- pytest.fail("Set STUDY_TEST_DATABASE_URL to a disposable migrated PostgreSQL database")
+ pytest.fail("Set P0_TEST_DATABASE_URL to a disposable migrated PostgreSQL database")
engine = create_engine(url)
assert engine.dialect.name == "postgresql"
factory = sessionmaker(bind=engine)
@@ -71,34 +71,3 @@ def test_postgres_ownership_and_progress(pg_repository):
progress.record_attempt(str(a), "fixture", "Q?", True, doc)
assert progress.get_summary(str(a))["total_attempts"] == 1
assert progress.get_summary(str(b))["total_attempts"] == 0
-
-
-def test_canonical_repository_and_grading_preserve_scoped_data(pg_repository):
- from study_supporter.application.contracts.context import AppContext
- from study_supporter.application.use_cases.learning import SubmitQuizUseCase
- from study_supporter.infrastructure.persistence.sqlalchemy.repositories import (
- DocumentRepository,
- )
-
- _, factory, (a, b) = pg_repository
- repository = DocumentRepository(factory)
- document = repository.create(str(a), "canonical.pdf", "fixture-hash")
- repository.update(str(a), document["id"], status="ready", chunk_count=1)
- repository.update(str(a), document["id"], concept_graph_json={"nodes": [], "edges": []})
- assert repository.find_hash(str(a), "fixture-hash")["id"] == document["id"]
- assert repository.find_hash(str(b), "fixture-hash") is None
- with pytest.raises(EvidenceNotFound):
- repository.get(str(b), document["id"])
- question = {
- "question": "Q?",
- "options": ["a", "b", "c", "d"],
- "correct_index": 1,
- "explanation": "fixture",
- }
- progress = ProgressDB(factory)
- submit = SubmitQuizUseCase(repository, progress)
- with pytest.raises(EvidenceNotFound):
- submit.execute(AppContext(str(b)), document["id"], question, 1)
- assert submit.execute(AppContext(str(a)), document["id"], question, 1).is_correct
- assert progress.get_summary(str(a))["total_attempts"] == 1
- assert progress.get_summary(str(b))["total_attempts"] == 0
diff --git a/backend/tests/unit/test_answer_scope.py b/backend/tests/unit/test_answer_scope.py
deleted file mode 100644
index 51cfd12..0000000
--- a/backend/tests/unit/test_answer_scope.py
+++ /dev/null
@@ -1,23 +0,0 @@
-from types import SimpleNamespace
-from unittest.mock import Mock
-
-import pytest
-
-from study_supporter.application.contracts.context import AppContext
-from study_supporter.application.contracts.learning import AnswerRequest
-from study_supporter.application.use_cases.answer_question import AnswerQuestionUseCase
-from study_supporter.domain.errors import EvidenceNotFound
-
-
-def test_answer_rejects_foreign_context_and_never_prefixes_identity_to_query():
- runner = Mock()
- runner.run.return_value = SimpleNamespace(final_answer="Fixture answer")
- context = AppContext("A", ("doc-a",))
- evidence = SimpleNamespace(context=context, last_evidence=["stale citation"])
- service = AnswerQuestionUseCase(runner, evidence)
- with pytest.raises(EvidenceNotFound):
- service.execute(AnswerRequest(AppContext("B", ("doc-a",)), "question"))
- runner.run.assert_not_called()
- result = service.execute(AnswerRequest(context, "question"))
- runner.run.assert_called_once_with("question")
- assert result.answer == "Fixture answer" and result.evidences == () and result.trace_id
diff --git a/backend/tests/unit/test_chat_rerun.py b/backend/tests/unit/test_chat_rerun.py
deleted file mode 100644
index 54df1af..0000000
--- a/backend/tests/unit/test_chat_rerun.py
+++ /dev/null
@@ -1,43 +0,0 @@
-from streamlit.testing.v1 import AppTest
-
-
-def chat_fixture():
- import streamlit as st
- from apps.streamlit_legacy.components.chat import render_chat
- from study_supporter.application.contracts.learning import AnswerResult
- from study_supporter.application.contracts.retrieval import Evidence
-
- class Session:
- def answer(self, question):
- return AnswerResult(
- "Fixture answer",
- (
- Evidence(
- "chunk-a",
- "doc-a",
- "content",
- "fixture.pdf",
- 1,
- 2,
- ),
- ),
- "fixture-trace",
- )
-
- st.session_state.setdefault("chat_history", [])
- st.session_state.orchestrator = True
- st.session_state.document_session = Session()
- render_chat()
-
-
-def test_actual_evidence_survives_chat_reruns():
- app = AppTest.from_function(chat_fixture).run()
- app.chat_input[0].set_value("Question").run()
- assert not app.exception
- assert len(app.session_state["chat_history"]) == 2
- for _ in range(2):
- assert any(
- "fixture.pdf" in block.value and "chunk-a" in block.value for block in app.markdown
- )
- app.run()
- assert not app.exception
diff --git a/backend/tests/unit/test_chunking_edge_cases.py b/backend/tests/unit/test_chunking_edge_cases.py
index 254f997..ea182ef 100644
--- a/backend/tests/unit/test_chunking_edge_cases.py
+++ b/backend/tests/unit/test_chunking_edge_cases.py
@@ -1,15 +1,15 @@
import fitz
import pytest
-from study_supporter.domain.upload_validation import validate_pdf_upload
-from study_supporter.ai.ingestion.chunking import (
+from src.documents.upload_validation import validate_pdf_upload
+from src.rag.chunker import (
compute_breakpoints,
compute_distances,
flatten_pages_to_sentences,
group_sentences_into_chunks,
)
-from study_supporter.infrastructure.documents.pymupdf_parser import parse_pdf
-from study_supporter.domain.documents import DocumentPage
+from src.rag.pdf_parser import parse_pdf
+from src.rag.schemas import DocumentPage
from study_supporter.domain.errors import DocumentUnsupported
from study_supporter.domain.errors import EmbeddingUnavailable
@@ -73,7 +73,7 @@ def test_invalid_upload(name, mime, content):
def test_incomplete_embeddings_fail_closed():
from unittest.mock import Mock
- from study_supporter.infrastructure.embeddings.sentences import embed_sentences
+ from src.rag.chunker import embed_sentences
sentences = flatten_pages_to_sentences(
[DocumentPage(source="fixture.pdf", page_number=1, text="First sentence. Second sentence.")]
diff --git a/backend/tests/unit/test_citations.py b/backend/tests/unit/test_citations.py
index d676fc5..8391dac 100644
--- a/backend/tests/unit/test_citations.py
+++ b/backend/tests/unit/test_citations.py
@@ -1,26 +1,22 @@
-from unittest.mock import Mock
-from study_supporter.application.contracts.context import AppContext
-from study_supporter.application.contracts.retrieval import Evidence
-from study_supporter.orchestration.legacy_react.tools.retrieve_evidence import RetrieveEvidenceTool
+from unittest.mock import Mock, patch
+
+from src.agent.tools.search_docs import SearchDocsTool
+from src.rag.schemas import Chunk
def test_citations_require_actual_retrieved_provenance_and_do_not_stay_stale():
- retrieval = Mock()
- retrieval.execute.return_value = [
- Evidence(
- document_id="doc-a",
- chunk_id="chunk-a",
- source="fixture.pdf",
- page_start=1,
- page_end=2,
- text="content",
- score=1.0,
- )
- ]
- tool = RetrieveEvidenceTool(retrieval, AppContext("A", ("doc-a",)))
- assert "fixture.pdf" in tool.run("question")
- query = retrieval.execute.call_args.args[0]
- assert query.user_id == "A" and query.document_ids == ("doc-a",)
+ chunk = Chunk(
+ chunk_id="chunk-a",
+ source="fixture.pdf",
+ page_start=1,
+ page_end=2,
+ text="content",
+ sentence_count=2,
+ )
+ tool = SearchDocsTool(Mock(), Mock(), Mock(), document_id="doc-a")
+ with patch("src.agent.tools.search_docs.hybrid_search", return_value=[chunk]):
+ tool.run("question")
+ assert tool.last_evidence[0].document_id == "doc-a"
assert tool.last_evidence[0].chunk_id == "chunk-a"
tool.run("")
assert tool.last_evidence == []
diff --git a/backend/tests/unit/test_concept_graph.py b/backend/tests/unit/test_concept_graph.py
index 86811c4..9254c9d 100644
--- a/backend/tests/unit/test_concept_graph.py
+++ b/backend/tests/unit/test_concept_graph.py
@@ -1,7 +1,7 @@
import pytest
from pydantic import ValidationError
-from study_supporter.domain.knowledge_graph import ConceptGraph
+from src.graph.schemas import ConceptGraph
def test_unknown_edge_cannot_create_an_invented_node():
diff --git a/backend/tests/unit/test_document_ownership.py b/backend/tests/unit/test_document_ownership.py
index 4d56026..fb88e96 100644
--- a/backend/tests/unit/test_document_ownership.py
+++ b/backend/tests/unit/test_document_ownership.py
@@ -2,10 +2,10 @@
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
-from study_supporter.infrastructure.persistence.sqlalchemy.database import Base
-from study_supporter.infrastructure.persistence.sqlalchemy.models import Document, QuizAttempt, User
-from study_supporter.infrastructure.persistence.sqlalchemy import document_repository as documents
-from study_supporter.infrastructure.persistence.sqlalchemy.progress_repository import ProgressDB
+from src.db.database import Base
+from src.db.models import Document, QuizAttempt, User
+from src.documents import document_service as documents
+from src.memory.progress_db import ProgressDB
from study_supporter.domain.errors import EvidenceNotFound
diff --git a/backend/tests/unit/test_legacy_retrieval.py b/backend/tests/unit/test_legacy_retrieval.py
index d6fe2ec..d65a67d 100644
--- a/backend/tests/unit/test_legacy_retrieval.py
+++ b/backend/tests/unit/test_legacy_retrieval.py
@@ -2,11 +2,8 @@
import pytest
-from study_supporter.infrastructure.retrieval.hybrid_adapter import (
- hybrid_search,
- reciprocal_rank_fusion,
-)
-from study_supporter.domain.documents import Chunk
+from src.rag.hybrid_retriever import hybrid_search, reciprocal_rank_fusion
+from src.rag.schemas import Chunk
from study_supporter.ai.retrieval.rrf import reciprocal_rank_fusion as core_rrf
diff --git a/backend/tests/unit/test_migrations_sqlite.py b/backend/tests/unit/test_migrations_sqlite.py
index 9ba5914..eeacd97 100644
--- a/backend/tests/unit/test_migrations_sqlite.py
+++ b/backend/tests/unit/test_migrations_sqlite.py
@@ -61,7 +61,7 @@ def test_imports_do_not_connect_or_create_tables(monkeypatch):
[
sys.executable,
"-c",
- "import study_supporter.infrastructure.persistence.sqlalchemy.auth_repository, study_supporter.infrastructure.persistence.sqlalchemy.document_repository, study_supporter.infrastructure.persistence.sqlalchemy.progress_repository",
+ "import src.auth.auth_service, src.documents.document_service, src.memory.progress_db",
],
capture_output=True,
text=True,
diff --git a/backend/tests/unit/test_notes_isolation.py b/backend/tests/unit/test_notes_isolation.py
index b4f775e..ad6fa55 100644
--- a/backend/tests/unit/test_notes_isolation.py
+++ b/backend/tests/unit/test_notes_isolation.py
@@ -1,9 +1,8 @@
from unittest.mock import Mock
-from study_supporter.application.use_cases.learning import SaveNoteUseCase, GetProgressUseCase
-from study_supporter.orchestration.legacy_react.tools.get_progress import GetProgressTool
-from study_supporter.orchestration.legacy_react.tools.save_note import SaveNoteTool
-from study_supporter.infrastructure.persistence.chroma.note_repository import LongTermMemory
+from src.agent.tools.get_progress import GetProgressTool
+from src.agent.tools.save_note import SaveNoteTool
+from src.memory.long_term import LongTermMemory
def test_notes_queries_always_use_the_bound_identity():
@@ -16,8 +15,8 @@ def test_notes_queries_always_use_the_bound_identity():
def test_llm_cannot_override_bound_tool_identity():
memory, progress = Mock(), Mock()
- note_tool = SaveNoteTool(SaveNoteUseCase(memory), "B")
- progress_tool = GetProgressTool(GetProgressUseCase(progress), "B")
+ note_tool = SaveNoteTool(memory, "B")
+ progress_tool = GetProgressTool(progress, "B")
note_tool.safe_run(note="text", user_id="A")
progress_tool.safe_run(user_id="A")
memory.save_note.assert_not_called()
diff --git a/backend/tests/unit/test_provider_errors.py b/backend/tests/unit/test_provider_errors.py
index 6fd3f67..ff61c74 100644
--- a/backend/tests/unit/test_provider_errors.py
+++ b/backend/tests/unit/test_provider_errors.py
@@ -3,12 +3,9 @@
import pytest
import requests
-from study_supporter.domain.provider_errors import ProviderAuthenticationError, ProviderUnavailable
-from study_supporter.infrastructure.llm.multi_provider_llm import MultiProviderLLM
-from study_supporter.infrastructure.llm.openai_compatible_client import (
- OpenAICompatibleClient,
- RateLimitError,
-)
+from src.llm.errors import ProviderAuthenticationError, ProviderUnavailable
+from src.llm.multi_provider_llm import MultiProviderLLM
+from src.llm.openai_compatible_client import OpenAICompatibleClient, RateLimitError
@pytest.mark.parametrize(
diff --git a/backend/tests/unit/test_quiz_validation.py b/backend/tests/unit/test_quiz_validation.py
index 961d649..911596d 100644
--- a/backend/tests/unit/test_quiz_validation.py
+++ b/backend/tests/unit/test_quiz_validation.py
@@ -1,10 +1,8 @@
import pytest
from pydantic import ValidationError
-from study_supporter.orchestration.legacy_react.tools.generate_quiz import QuizQuestion
-from study_supporter.ai.assessment.legacy_parser import (
- parse_quiz_from_text as _parse_quiz_from_text,
-)
+from src.agent.tools.generate_quiz import QuizQuestion
+from ui.components.quiz_arena import _parse_quiz_from_text
@pytest.mark.parametrize("answer", [None, -1, 4, True, "1"])
diff --git a/backend/tests/unit/test_session_reset.py b/backend/tests/unit/test_session_reset.py
index f5fdb19..a9f4fb0 100644
--- a/backend/tests/unit/test_session_reset.py
+++ b/backend/tests/unit/test_session_reset.py
@@ -1,4 +1,4 @@
-from apps.streamlit_legacy.session import reset_session_on_logout
+from src.auth.session import reset_session_on_logout
def test_logout_drops_all_user_data_and_future_keys():
@@ -27,7 +27,7 @@ def test_logout_drops_all_user_data_and_future_keys():
def test_login_as_b_resets_residual_a_state(monkeypatch):
- from apps.streamlit_legacy.components import auth
+ from ui.components import auth
state = {"store": "A", "quiz_history": ["A"], "theme_mode": "light"}
diff --git a/config/README.md b/config/README.md
deleted file mode 100644
index 1bdd0ef..0000000
--- a/config/README.md
+++ /dev/null
@@ -1,19 +0,0 @@
-# Environment templates
-
-Choose the template for the execution environment:
-
-| Execution | Copy from | Local destination |
-| --- | --- | --- |
-| Docker Compose / PostgreSQL | `config/docker.env.example` | `.env.docker` |
-| Native Streamlit / SQLite | `config/local.env.example` | `.env` |
-
-Real files are ignored, excluded from Docker context and kept local. Existing
-credentials and Compose database passwords are preserved during consolidation.
-Compose reads `.env.docker` explicitly; native entrypoints load `.env` before
-creating `Settings`. Process environment and optional Streamlit secrets are mapped
-once by the presentation bridge. The core never reads Streamlit secrets or dotenv.
-
-Native setup also needs `data/` and an explicit Alembic upgrade before launching
-`python -m streamlit run apps/streamlit_legacy/main.py`. Keep BGE-M3/1024D defaults
-when opening existing vectors. Configure a working Ollama model or cloud provider
-for chat/quiz; empty API key values are valid for Ollama usage.
diff --git a/docs/architecture/adr/README.md b/docs/architecture/adr/README.md
index f5e2e65..5f4b5ad 100644
--- a/docs/architecture/adr/README.md
+++ b/docs/architecture/adr/README.md
@@ -1,4 +1,4 @@
-# Architecture decisions
+# Phase 0 architecture decisions
Status: accepted for implementation. Owner: ManhT005 (repository maintainer).
Revisit via a separate PR with tests and migration evidence.
@@ -6,13 +6,11 @@ Revisit via a separate PR with tests and migration evidence.
| ADR | Decision | Rationale and consequence |
| --- | --- | --- |
| 0001 | Modular monolith before v1 | Keep one deployable application; no microservice coordination cost. |
-| 0002 | Single `study-supporter` distribution, Python src layout | Installed imports use `study_supporter`; root `src`/`ui` removed after consolidation tests. |
-| 0003 | LangGraph belongs to orchestration | Core algorithms and use cases remain framework independent; no LangGraph dependency during consolidation. |
+| 0002 | Single `study-supporter` distribution, Python src layout | Installed imports use `study_supporter`; retain legacy `src`/`ui` during extraction. |
+| 0003 | LangGraph belongs to orchestration | Core algorithms and use cases remain framework independent; no LangGraph dependency in P0. |
| 0004 | PostgreSQL is authoritative; Chroma stores vectors | Resolve collections using authenticated ownership. Preserve existing vector IDs/dimensions and string quiz user IDs until a reviewed data migration. |
| 0005 | Validate local Docker before UI/API split | Persistent app/PG/model volumes; Ollama optional, no models fetched at build time. |
| 0006 | Reproducible experiments | Freeze RRF semantics and synthetic fixtures; new retrieval changes need datasets, baseline and measured results. |
Existing populated schemas require backup and schema comparison before any manual
-Alembic stamp. Never auto-stamp, reset volumes, change vector dimensions or tag v1 during consolidation.
-
-See [repository consolidation](repository-consolidation.md) for the current resource, scope and dependency decisions.
+Alembic stamp. Never auto-stamp, reset volumes, change vector dimensions or tag v1 in P0.
diff --git a/docs/architecture/adr/repository-consolidation.md b/docs/architecture/adr/repository-consolidation.md
index ec03754..e1289fe 100644
--- a/docs/architecture/adr/repository-consolidation.md
+++ b/docs/architecture/adr/repository-consolidation.md
@@ -8,26 +8,12 @@ All product implementations migrate into one study-supporter distribution. Durin
each slice legacy modules may forward to canonical implementations, never vice versa.
Streamlit is presentation; authenticated AppContext supplies ownership to every use
case and tool. ORM/Chroma/SDK objects stay inside infrastructure/composition.
-All runtime callers now use canonical imports; the temporary src/ui aliases have
-been removed after retaining and running the original tests in backend/tests.
Preserve SQL tables/Alembic revision p0_0001, string quiz user IDs, documents_,
user_memory, BGE-M3/1024D, semantic chunk hashes, BM25 tokenization, RRF and ReAct.
Deterministic vendor imports require exact-module allowlists and negative gate tests.
No LangGraph/FastAPI/Next.js is added in consolidation.
-ApplicationFactory owns explicit Database disposal and a lazy shared embedding
-provider. Account-bound LearningSession/RetrieveEvidenceTool instances are created
-per authenticated document session. Ingestion receives repository/parser/embedding
-and vector adapters, emits correlated progress and verifies IDs before READY.
-Deterministic vendor exceptions are exact modules: Pydantic schemas/JSON parsing,
-NumPy chunking and NetworkX graph algorithms. No SDK or network exception exists.
-
-Dependency declarations are centralized in backend/pyproject.toml, deployment/dev
-locks in requirements and environment templates in config. Native and Docker env
-files are local inputs; their existing secret values are preserved. Existing SQL
-and Chroma data require no migration or reindex for this refactor.
-
Local slice branches form a reviewable dependency stack rooted at origin/develop;
each commit/branch checkpoint maps to one plan responsibility. No merge into develop
or remote publication is implied by local implementation. Submit/rebase the slices
diff --git a/docs/architecture/module-boundaries.md b/docs/architecture/module-boundaries.md
index 0d4d958..8efdbb7 100644
--- a/docs/architecture/module-boundaries.md
+++ b/docs/architecture/module-boundaries.md
@@ -1,24 +1,19 @@
# Module ownership and dependency direction
-Owner: repository maintainer; changes require scoped PR review.
+Owner for each layer during Phase 0: repository maintainer; changes require PR review.
-| Layer | Allowed internal dependencies |
-| --- | --- |
-| domain | domain |
-| ai | ai, domain |
-| application | application, domain, ai |
-| infrastructure | infrastructure, application, domain, ai, config |
-| orchestration | orchestration, application, domain, ai |
-| interfaces | interfaces, application, domain |
-| bootstrap | all layers |
+| Layer | Responsibility | Allowed internal dependencies |
+| --- | --- | --- |
+| domain | Entities and business validation | domain |
+| ai | Pure algorithms, including unchanged RRF | ai, domain |
+| application | Contracts, ports, use cases | application, domain, ai |
+| infrastructure | Port implementations and external drivers | application, domain, ai |
+| orchestration (future) | Workflow state, injected use cases | application, domain, ai |
+| interfaces (future) | Authentication, input/output adaptation | application, domain |
+| bootstrap | Explicit composition | all layers |
-Pure layers permit stdlib and only these exact deterministic exceptions:
-Pydantic in domain documents/assessment/knowledge_graph and AI JSON parsing;
-NumPy in AI chunking; NetworkX in AI graph algorithms. Allowlisting a module does
-not permit network/driver imports. AST checks include relative and nested imports.
-Streamlit components cannot import infrastructure or orchestration; entrypoints
-and helper scripts cannot import the removed `src`/`ui` namespaces.
-
-No `sys.path` modification, import-time engine/model construction, private agent
-reasoning in UI or placeholder framework folders. Entrypoints load environment
-configuration explicitly and application requests carry authenticated scope.
+Core layers must not import legacy `src`, `ui`, bootstrap, infrastructure,
+frameworks, database drivers, provider SDKs or network clients. No side effects at import.
+An AST gate checks absolute and relative imports, including imports nested in functions.
+Legacy code may forward to the new package; the reverse dependency is forbidden.
+No `sys.path` mutation. No placeholder directories for unimplemented features.
diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md
index bafbe00..450a0d1 100644
--- a/docs/architecture/overview.md
+++ b/docs/architecture/overview.md
@@ -1,36 +1,13 @@
-# Application architecture
+# Engineering foundation
-One `study-supporter` distribution contains all product use cases. Streamlit under
-`apps/streamlit_legacy` renders application results; `bootstrap.ApplicationFactory`
-owns explicit database lifecycle, lazy shared embeddings and per-account learning
-sessions. No user-bound retriever or agent is cached across accounts.
+Self Study Supporter remains a modular monolith with the existing Streamlit entrypoint.
+Phase 0 extracts one pure retrieval slice into the `study-supporter` distribution,
+then adds correctness tests, explicit database migrations and offline quality gates.
+Next.js, FastAPI, LangGraph and new retrieval algorithms belong to later phases.
-| Layer | Responsibility |
-| --- | --- |
-| domain | Documents, quiz/graph validation, authenticated errors, conversation policy |
-| ai | Deterministic chunking, RRF, graph ordering and quiz/JSON parsing |
-| application | DTOs, ports, ingestion/retrieval/answer/learning services |
-| infrastructure | SQLAlchemy, Chroma, PyMuPDF, embeddings and LLM SDK/HTTP adapters |
-| orchestration/legacy_react | Original text parser and five-step tool workflow |
-| bootstrap | Resource wiring and provider priority |
-| apps/streamlit_legacy | Authentication/session adapter and presentation |
+Composition remains in the legacy sidebar until application contracts are established.
+PostgreSQL owns user/document/quiz records; persistent Chroma stores vectors and notes.
+Both stores must be backed up at the same quiescent application boundary.
-Dependencies point from entrypoints/bootstrap to application, domain and injected
-adapters. Application may call pure AI algorithms; pure layers cannot import UI,
-infrastructure, orchestration, network clients or provider SDKs. Exact deterministic
-vendor exceptions are checked by the AST gate and negative tests.
-
-PostgreSQL owns accounts/documents/quiz attempts; Chroma retains `documents_`
-and `user_memory`. Immutable AppContext binds identity from authentication; tools
-accept content/query parameters only. Existing Alembic revision/string quiz IDs,
-BGE-M3/1024D, hashes, tokenizer, RRF ordering and prompts are preserved.
-
-Ingestion is synchronous with trace-linked progress, per-process user/hash locking
-and READY only after verified chunk IDs. Multi-process hash uniqueness is a future
-schema/concurrency task. Quiz generation still samples the first five chunks;
-retrieval quality and Vietnamese tokenization changes require separate benchmarks.
-
-Root `src/` and `ui/` have been removed. `evaluation/` contains opt-in experiments;
-tests are unified under `backend/tests`. Next.js/FastAPI/LangGraph are not introduced.
-See [boundaries](module-boundaries.md), [ADR](adr/repository-consolidation.md),
-[historical baseline](current-state.md) and [current acceptance](../reports/repository-consolidation-acceptance.md).
+See [baseline](current-state.md), [boundaries](module-boundaries.md),
+[decisions](adr/README.md) and [Phase 0 plan](../plans/PHASE_0_ENGINEERING_FOUNDATION.md).
diff --git a/docs/archive/README.md b/docs/archive/README.md
deleted file mode 100644
index 0549246..0000000
--- a/docs/archive/README.md
+++ /dev/null
@@ -1,8 +0,0 @@
-# Historical engineering notes
-
-`legacy-notes/` preserves the tracked sprint notes from the removed runtime tree.
-Paths, prompts and commands inside them describe historical implementations.
-Use the [current architecture](../architecture/overview.md),
-[operations](../operations/docker.md) and [acceptance report](../reports/repository-consolidation-acceptance.md)
-for the canonical package and current commands. Migration IDs and original
-foundation evidence remain at their existing documented locations.
diff --git a/docs/docker-local-foundation.md b/docs/docker-local-foundation.md
index 66a384c..689fafd 100644
--- a/docs/docker-local-foundation.md
+++ b/docs/docker-local-foundation.md
@@ -12,7 +12,7 @@ and a one-shot Alembic service runs before app startup. Existing schemas require
```powershell
git fetch origin
git switch feature/docker-local-foundation
-Copy-Item config/docker.env.example .env.docker
+Copy-Item .env.docker.example .env.docker
# Edit .env.docker; replace POSTGRES_PASSWORD with a strong password.
docker compose --env-file .env.docker config --quiet
docker compose --env-file .env.docker up -d --build
diff --git a/docs/operations/docker.md b/docs/operations/docker.md
index 4cd0fd8..4334791 100644
--- a/docs/operations/docker.md
+++ b/docs/operations/docker.md
@@ -9,7 +9,7 @@ never during build. Download time depends on bandwidth; BGE-M3 is a large model.
PowerShell:
```powershell
-Copy-Item config/docker.env.example .env.docker
+Copy-Item .env.docker.example .env.docker
# Edit POSTGRES_PASSWORD; keep provider keys blank for the local baseline.
docker compose --env-file .env.docker config --quiet
docker compose --env-file .env.docker up -d --build --wait
@@ -17,7 +17,7 @@ docker compose --env-file .env.docker ps
Invoke-WebRequest http://localhost:8501/_stcore/health
```
-POSIX uses `cp config/docker.env.example .env.docker` and
+POSIX uses `cp .env.docker.example .env.docker` and
`curl --fail http://localhost:8501/_stcore/health`; Compose commands are identical.
Health 200 proves Streamlit liveness, not DB/model readiness. Run functional smoke
separately; offline fake vectors cannot establish BGE model quality or LLM availability.
@@ -34,9 +34,6 @@ Host mode: `OLLAMA_BASE_URL=http://host.docker.internal:11434`. Ensure Docker ca
reach the host listener. Container mode: set `http://ollama:11434`, then
`docker compose --env-file .env.docker --profile local-ai up -d`.
Provision explicitly with `docker compose --env-file .env.docker exec ollama ollama pull qwen3:1.7b`.
-Set `OLLAMA_MODEL=qwen3:1.7b` in `.env.docker` when using that model and recreate
-the app. The preserved UI default is `qwen2.5:1.5b`; it must be installed if you
-keep the default. Real-model smoke explicitly selects `qwen3:1.7b`.
No GPU required. Do not open the listener to public networks.
## Backup and isolated restore
@@ -47,8 +44,8 @@ The helper stops app writes, dumps SQL and snapshots `/app/data` at the same bou
then restarts the app if it was running. A failed backup has no completed manifest.
```powershell
-python scripts/docker_backup.py backup data/backups/local-snapshot --project-name self-study-supporter
-python scripts/docker_backup.py restore data/backups/local-snapshot --project-name restore-check
+python scripts/docker_backup.py backup data/backups/p0-001 --project-name self-study-supporter
+python scripts/docker_backup.py restore data/backups/p0-001 --project-name p0-restore-check
```
Restore refuses the source project and any existing target containers/volumes.
@@ -58,9 +55,9 @@ not part of the snapshot. Restoring old data is never an automatic schema stamp.
## Dependency locks
-`backend/pyproject.toml` declares direct dependencies; `requirements/runtime.txt` locks the
-Linux x86_64/Python 3.11 CPU deployment. `requirements/dev.txt` locks offline test tooling.
-See [lock regeneration](../../requirements/README.md); review the diff and rebuild Docker.
+`requirements.in` pins direct runtime dependencies; `requirements.txt` locks the
+Linux x86_64/Python 3.11 CPU deployment. `requirements-dev.txt` locks offline test tooling.
+Regenerate with uv 0.13.0, review the diff, then clean-build before committing.
The existing `.env`, uploaded data and secrets are excluded by `.dockerignore`.
## Executable smoke commands
diff --git a/docs/operations/migrations.md b/docs/operations/migrations.md
index 2ca2f40..244b56d 100644
--- a/docs/operations/migrations.md
+++ b/docs/operations/migrations.md
@@ -1,6 +1,6 @@
# Database lifecycle
-`backend/src/study_supporter/infrastructure/persistence/sqlalchemy/models.py` is the schema source of truth. Alembic revision `p0_0001`
+`src/db/models.py` is the schema source of truth. Alembic revision `p0_0001`
matches the legacy User/Document/QuizAttempt schema. Integer users/documents and
historical string quiz user IDs are intentionally preserved: no unreviewed type
conversion or FK/backfill for legacy quiz identities. New attempts validate the
diff --git a/docs/reports/repository-consolidation-acceptance.md b/docs/reports/repository-consolidation-acceptance.md
deleted file mode 100644
index 8d41513..0000000
--- a/docs/reports/repository-consolidation-acceptance.md
+++ /dev/null
@@ -1,77 +0,0 @@
-# Repository consolidation acceptance
-
-Implemented on 2026-10-14 from `origin/develop` at
-`5c9a16d2eb133ec4f20cdc6093b2cda970755603`. Base foundation CI was independently
-verified successful; it is not counted as CI evidence for these local changes.
-
-All product implementations now live in `backend/src/study_supporter`. The root
-`src/`, `ui/` and split test tree are removed. Streamlit calls account-bound
-application services, and ReAct tools take identity from AppContext rather than
-LLM arguments or a user-ID prefix in the question. Root commands are redirects.
-
-Dependencies are declared once in `backend/pyproject.toml`; generated locks live
-in `requirements/`. Docker/native templates live in `config/`. Existing local
-`.env`/`.env.docker` credentials remain unchanged and ignored. Every locked runtime
-version is unchanged; the dev lock adds the existing BM25 dependency for offline checks.
-
-Local commits/checkpoints are a dependency stack based on develop:
-
-| Slice | Commit | Branch checkpoint |
-| --- | --- | --- |
-| Contracts | 2965b38 | refactor/core-contracts |
-| Configuration/bootstrap | a5213b8 | refactor/config-bootstrap |
-| Persistence/ownership | d75c05a | refactor/persistence-repositories |
-| Document ingestion | 98bdd37 | refactor/document-ingestion |
-| Retrieval adapters | f5c45cf | refactor/retrieval-adapters |
-| Learning services | 45b971c | refactor/learning-services |
-| ReAct/Streamlit boundary | f478856 | refactor/agent-ui-boundary |
-| Requirements/env cleanup | 0d79829 | refactor/legacy-cleanup |
-| Namespace removal, QA and docs | f453d90 | refactor/legacy-cleanup |
-| Citation rerun fix | final follow-up commit (HEAD) | refactor/legacy-cleanup |
-
-Submit/rebase the slices in plan order after review. No push, remote PR, merge or
-release tag is part of this local execution.
-
-| Verification | Evidence |
-| --- | --- |
-| Original baseline | 91 offline tests on Windows |
-| Final offline suite | 122 tests; all old tests retained and collected in backend/tests |
-| Windows | Python 3.12.7: 122 passed, 11.68 seconds |
-| Linux | Python 3.11 in Linux Docker: 122 passed, 25.74 seconds |
-| Architecture/lint/format | Import gate, caller/presentation boundaries, Ruff check/format passed |
-| Package | Wheel/sdist built; wheel imported outside repository with src/ui unavailable |
-| Clean local clone | Editable install, 122 tests (24.15 seconds), Ruff/import gates and fresh wheel/sdist build passed without env/secrets or root src/ui |
-| PostgreSQL 16 fresh schema | Alembic upgrade/check, no drift, 3 integration tests passed |
-| Docker and Streamlit | Final image healthy; AppTest registration/logout/B login, fake services seed/verify and absence of src/ui namespaces passed |
-| Historical SQL/Chroma data | Baseline SQL/Chroma snapshot restored into consolidation-restore-20261014; canonical auth/chat/citations/quiz/progress/notes and A/B isolation verification passed |
-| Real model smoke | BGE-M3/1024D and Ollama qwen3:1.7b: canonical ingestion/retrieval/ReAct/evidence/quiz/persisted progress passed |
-| Real browser automation | Playwright 1.63.0/Chromium passed registration/upload/chat/citations/quiz/grade/logout/B isolation/A resume with both deterministic providers and real BGE-M3/Ollama qwen3:1.7b |
-| Remote CI and human acceptance | Pending publication/review by maintainer |
-
-Fresh synthetic SQL/Chroma seed was verified again after Compose down/up without
-removing volumes. The backup baseline is retained locally under
-`data/backups/consolidation-baseline-20261014`; restored/smoke project volumes are
-also retained, and disposable containers are stopped after checks.
-Browser evidence/screenshots are retained locally in `data/browser-consolidation`;
-the model override ran only in a disposable test container. The primary app retains
-its original provider configuration and is restored on localhost:8501.
-
-Preserved data contracts: Alembic `p0_0001`, SQL tables/columns, string
-`QuizAttempt.user_id`, Chroma `documents_` and `user_memory`, BGE-M3/1024D,
-chunk hashes/provenance, BM25 tokenizer, RRF tie ordering, graph extraction prompt,
-provider priority and ReAct five-step ceiling. No reindex, schema change or volume
-reset is required. Historical engineering notes are retained in docs/archive.
-
-Known limits remain explicit: quiz context still samples the first five chunks;
-ingestion hash locking protects one process, not multiple workers; PDF scans need
-OCR; generated quiz sets/history are session-scoped while attempts and graphs
-persist in SQL; model smoke uses synthetic accounts and is not a quality benchmark. Human
-browser review, Tech Lead/Test Lead sign-off and final remote CI are still required
-before claiming the plan's overall merge acceptance.
-
-Browser checks exposed a pre-existing presentation bug: evidence chips were drawn
-only for the live answer and disappeared immediately after Streamlit rerun.
-The follow-up fix keeps Evidence DTOs with each assistant history item and renders
-them on subsequent runs; AppTest reproduces the rerun path. This is an intentional
-bug fix to citation visibility, with no retrieval/model/schema change. Earlier
-browser citation failures alone did not establish that the model skipped retrieval.
diff --git a/eval_test.py b/eval_test.py
index 39a9a26..f9fbea9 100644
--- a/eval_test.py
+++ b/eval_test.py
@@ -1,6 +1,65 @@
-"""Compatibility command; online evaluation lives in evaluation.runner."""
+"""Opt-in online evaluation against a dedicated authenticated fixture account."""
+
+import argparse
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument(
+ "--user-id", required=True, type=int, help="Dedicated evaluation account ID"
+ )
+ parser.add_argument("--dataset", default="data/eval_dataset.json")
+ parser.add_argument("--output", default="data/eval_results_test1.json")
+ args = parser.parse_args()
+
+ from dotenv import load_dotenv
+
+ load_dotenv()
+ from src.db.lifecycle import verify_schema
+ from src.documents.document_service import get_latest_ready_document
+ from src.agent.orchestrator import ReActOrchestrator
+ from src.agent.tools.generate_quiz import GenerateQuizTool
+ from src.agent.tools.get_progress import GetProgressTool
+ from src.agent.tools.save_note import SaveNoteTool
+ from src.agent.tools.search_docs import SearchDocsTool
+ from src.eval.eval_runner import load_eval_dataset, run_eval, save_results
+ from src.llm.ollama_client import OllamaClient
+ from src.memory.long_term import LongTermMemory
+ from src.memory.progress_db import ProgressDB
+ from src.rag.bm25_index import BM25Index
+ from src.rag.embedding_provider import LocalEmbeddingProvider
+ from src.rag.vector_store import VectorStore
+
+ verify_schema()
+ document = get_latest_ready_document(args.user_id)
+ if document is None:
+ parser.error("Evaluation account has no ready document")
+ store = VectorStore(collection_name=document["chroma_collection_name"])
+ chunks = store.load_all_chunks()
+ if not chunks:
+ parser.error("Document vectors are unavailable")
+ bm25 = BM25Index(chunks)
+ provider = LocalEmbeddingProvider() # Preserve BGE-M3 / 1024D baseline.
+
+ def embed_query_fn(question):
+ return provider.embed([question], task_type="RETRIEVAL_QUERY")[0]
+
+ llm = OllamaClient(model="qwen3:1.7b")
+ memory = LongTermMemory(store, embed_query_fn)
+ progress = ProgressDB()
+ identity = str(args.user_id)
+ tools = [
+ SearchDocsTool(store, bm25, embed_query_fn, document_id=str(document["id"])),
+ GenerateQuizTool(llm),
+ SaveNoteTool(memory, identity),
+ GetProgressTool(progress, identity),
+ ]
+ orchestrator = ReActOrchestrator(llm, tools)
+ dataset = load_eval_dataset(args.dataset)
+ results = run_eval(dataset[:5], store, bm25, embed_query_fn, llm, orchestrator)
+ save_results(results, args.output)
+ print(f"Saved {len(results)} evaluation results; online model calls were explicitly requested.")
-from evaluation.runner import main
if __name__ == "__main__":
main()
diff --git a/evaluation/README.md b/evaluation/README.md
deleted file mode 100644
index 7aea698..0000000
--- a/evaluation/README.md
+++ /dev/null
@@ -1,16 +0,0 @@
-# Opt-in evaluation
-
-No evaluation module runs a network call on import or during default pytest.
-Use a dedicated synthetic account with a ready owned document:
-
-```powershell
-python -m evaluation.runner --user-id 123 --dataset data/eval_dataset.json --output data/eval_results.json
-python -m evaluation.run_judge
-python -m evaluation.metrics
-```
-
-The comparison preserves the original RAG-only prompt, hybrid ranking and ReAct
-iteration/tool metrics, with personalized history only for personalized questions.
-The judge and similarity commands consume models and write under ignored `data/`.
-Scores from the small Ollama judge are exploratory, not an accepted quality benchmark.
-`eval_test.py` remains a command redirect to `evaluation.runner`.
diff --git a/evaluation/runner.py b/evaluation/runner.py
deleted file mode 100644
index beea985..0000000
--- a/evaluation/runner.py
+++ /dev/null
@@ -1,64 +0,0 @@
-"""Opt-in online comparison on a dedicated account's owned document."""
-
-import argparse
-import os
-from dataclasses import replace
-
-
-def main():
- parser = argparse.ArgumentParser(description=__doc__)
- parser.add_argument("--user-id", required=True, help="Dedicated fixture account ID")
- parser.add_argument("--dataset", default="data/eval_dataset.json")
- parser.add_argument("--output", default="data/eval_results.json")
- args = parser.parse_args()
- from dotenv import load_dotenv
- from study_supporter.bootstrap import ApplicationFactory
- from study_supporter.config import Settings
- from study_supporter.application.contracts.context import AppContext
- from study_supporter.orchestration.legacy_react.orchestrator import ReActOrchestrator
- from study_supporter.orchestration.legacy_react.tools.generate_quiz import GenerateQuizTool
- from study_supporter.orchestration.legacy_react.tools.retrieve_evidence import (
- RetrieveEvidenceTool,
- )
- from study_supporter.orchestration.legacy_react.tools.save_note import SaveNoteTool
- from study_supporter.orchestration.legacy_react.tools.get_progress import GetProgressTool
- from study_supporter.application.use_cases.learning import SaveNoteUseCase, GetProgressUseCase
- from study_supporter.infrastructure.persistence.chroma.note_repository import LongTermMemory
- from study_supporter.infrastructure.retrieval.bm25_adapter import BM25Index
- from evaluation.eval_runner import load_eval_dataset, run_eval, save_results
-
- load_dotenv()
- settings = replace(Settings.from_mapping(os.environ), ollama_model="qwen3:1.7b")
- with ApplicationFactory(settings) as services:
- services.verify_schema()
- context = AppContext(args.user_id)
- document = services.document_repository.latest(context.user_id)
- if document is None:
- parser.error("Evaluation account has no ready document")
- context = AppContext(context.user_id, (str(document["id"]),))
- store = services.vector_store(document)
- chunks = store.load_all_chunks()
- if not chunks:
- parser.error("Document vectors are unavailable")
- llm = services.provider("ollama").client
-
- def embed_query(question):
- return services.embedding.embed([question], "RETRIEVAL_QUERY")[0]
-
- tools = [
- RetrieveEvidenceTool(services.retriever(), context),
- GenerateQuizTool(llm),
- SaveNoteTool(SaveNoteUseCase(LongTermMemory(store, embed_query)), context.user_id),
- GetProgressTool(GetProgressUseCase(services.progress_repository), context.user_id),
- ]
- # The experimental comparison retains iteration/tool metrics and personalized history.
- agent = ReActOrchestrator(llm, tools)
- results = run_eval(
- load_eval_dataset(args.dataset)[:5], store, BM25Index(chunks), embed_query, llm, agent
- )
- save_results(results, args.output)
- print(f"Saved {len(results)} evaluation results; online model calls were explicitly requested.")
-
-
-if __name__ == "__main__":
- main()
diff --git a/docs/free-credit.md b/free-credit.md
similarity index 100%
rename from docs/free-credit.md
rename to free-credit.md
diff --git a/pytest.ini b/pytest.ini
index a4107d3..74bac7d 100644
--- a/pytest.ini
+++ b/pytest.ini
@@ -1,2 +1,2 @@
[pytest]
-testpaths = backend/tests/unit backend/tests/contract
+testpaths = tests backend/tests/unit backend/tests/contract
diff --git a/requirements-dev.in b/requirements-dev.in
new file mode 100644
index 0000000..5c545e1
--- /dev/null
+++ b/requirements-dev.in
@@ -0,0 +1,18 @@
+# Offline suite does not need Torch, Chroma or model weights.
+pytest==8.3.4
+ruff==0.9.10
+build==1.2.2.post1
+setuptools==75.6.0
+wheel==0.45.1
+numpy==1.26.4
+pydantic==2.10.4
+networkx==3.4.2
+requests==2.32.5
+sqlalchemy==2.0.36
+streamlit==1.41.1
+pymupdf==1.25.1
+python-dotenv==1.0.1
+bcrypt==4.2.1
+alembic==1.14.0
+psycopg2-binary==2.9.10
+google-genai==1.56.0
diff --git a/requirements/dev.txt b/requirements-dev.txt
similarity index 75%
rename from requirements/dev.txt
rename to requirements-dev.txt
index 663ea4e..3110c7a 100644
--- a/requirements/dev.txt
+++ b/requirements-dev.txt
@@ -1,7 +1,7 @@
# This file was autogenerated by uv via the following command:
-# uv pip compile backend/pyproject.toml --extra dev --python-version 3.11 --output-file requirements/dev.txt
+# uv pip compile requirements-dev.in --python-version 3.11 --output-file requirements-dev.txt
alembic==1.14.0
- # via study-supporter (backend/pyproject.toml)
+ # via -r requirements-dev.in
altair==5.5.0
# via streamlit
annotated-types==0.8.0
@@ -15,11 +15,11 @@ attrs==26.1.0
# jsonschema
# referencing
bcrypt==4.2.1
- # via study-supporter (backend/pyproject.toml)
+ # via -r requirements-dev.in
blinker==1.9.0
# via streamlit
build==1.2.2.post1
- # via study-supporter (backend/pyproject.toml)
+ # via -r requirements-dev.in
cachetools==5.5.2
# via streamlit
certifi==2026.7.22
@@ -48,7 +48,7 @@ gitpython==3.2.0
google-auth==2.62.0
# via google-genai
google-genai==1.56.0
- # via study-supporter (backend/pyproject.toml)
+ # via -r requirements-dev.in
greenlet==3.5.6
# via sqlalchemy
h11==0.16.0
@@ -85,13 +85,12 @@ mdurl==0.1.2
narwhals==2.27.1
# via altair
networkx==3.4.2
- # via study-supporter (backend/pyproject.toml)
+ # via -r requirements-dev.in
numpy==1.26.4
# via
- # study-supporter (backend/pyproject.toml)
+ # -r requirements-dev.in
# pandas
# pydeck
- # rank-bm25
# streamlit
packaging==24.2
# via
@@ -108,7 +107,7 @@ pluggy==1.6.0
protobuf==5.29.6
# via streamlit
psycopg2-binary==2.9.10
- # via study-supporter (backend/pyproject.toml)
+ # via -r requirements-dev.in
pyarrow==26.0.0
# via streamlit
pyasn1==0.6.4
@@ -119,7 +118,7 @@ pycparser==3.11
# via cffi
pydantic==2.10.4
# via
- # study-supporter (backend/pyproject.toml)
+ # -r requirements-dev.in
# google-genai
pydantic-core==2.27.2
# via pydantic
@@ -128,26 +127,24 @@ pydeck==0.9.3
pygments==2.21.0
# via rich
pymupdf==1.25.1
- # via study-supporter (backend/pyproject.toml)
+ # via -r requirements-dev.in
pyproject-hooks==1.3.3
# via build
pytest==8.3.4
- # via study-supporter (backend/pyproject.toml)
+ # via -r requirements-dev.in
python-dateutil==2.9.0.post0
# via pandas
python-dotenv==1.0.1
- # via study-supporter (backend/pyproject.toml)
+ # via -r requirements-dev.in
pytz==2026.5
# via pandas
-rank-bm25==0.2.2
- # via study-supporter (backend/pyproject.toml)
referencing==0.37.0
# via
# jsonschema
# jsonschema-specifications
requests==2.32.5
# via
- # study-supporter (backend/pyproject.toml)
+ # -r requirements-dev.in
# google-auth
# google-genai
# streamlit
@@ -158,9 +155,9 @@ rpds-py==2026.9.1
# jsonschema
# referencing
ruff==0.9.10
- # via study-supporter (backend/pyproject.toml)
+ # via -r requirements-dev.in
setuptools==75.6.0
- # via study-supporter (backend/pyproject.toml)
+ # via -r requirements-dev.in
six==1.17.0
# via python-dateutil
smmap==5.0.3
@@ -169,10 +166,10 @@ sniffio==1.3.1
# via google-genai
sqlalchemy==2.0.36
# via
- # study-supporter (backend/pyproject.toml)
+ # -r requirements-dev.in
# alembic
streamlit==1.41.1
- # via study-supporter (backend/pyproject.toml)
+ # via -r requirements-dev.in
tenacity==9.1.4
# via
# google-genai
@@ -201,4 +198,4 @@ watchdog==6.0.0
websockets==15.0.1
# via google-genai
wheel==0.45.1
- # via study-supporter (backend/pyproject.toml)
+ # via -r requirements-dev.in
diff --git a/requirements.in b/requirements.in
new file mode 100644
index 0000000..3c38dd5
--- /dev/null
+++ b/requirements.in
@@ -0,0 +1,20 @@
+# CPU baseline. Preserve the existing embedder and stored vector dimensions.
+google-genai==1.56.0
+python-dotenv==1.0.1
+pymupdf==1.25.1
+chromadb==0.5.23
+# Chroma 0.5 calls the legacy three-argument capture API.
+posthog==3.7.0
+rank-bm25==0.2.2
+pydantic==2.10.4
+sentence-transformers==3.3.1
+transformers==4.46.3
+torch==2.5.1+cpu
+numpy==1.26.4
+networkx==3.4.2
+sqlalchemy==2.0.36
+streamlit==1.41.1
+requests==2.32.5
+bcrypt==4.2.1
+psycopg2-binary==2.9.10
+alembic==1.14.0
diff --git a/requirements/runtime.txt b/requirements.txt
similarity index 88%
rename from requirements/runtime.txt
rename to requirements.txt
index 98172c2..3ab6b11 100644
--- a/requirements/runtime.txt
+++ b/requirements.txt
@@ -1,5 +1,5 @@
# This file was autogenerated by uv via the following command:
-# uv pip compile backend/pyproject.toml --extra runtime --python-version 3.11 --python-platform x86_64-unknown-linux-gnu --extra-index-url https://download.pytorch.org/whl/cpu --index-strategy unsafe-best-match --emit-index-url --output-file requirements/runtime.txt
+# uv pip compile requirements.in --python-version 3.11 --python-platform x86_64-unknown-linux-gnu --extra-index-url https://download.pytorch.org/whl/cpu --index-strategy unsafe-best-match --emit-index-url --output-file requirements.txt
--index-url https://pypi.org/simple
--extra-index-url https://download.pytorch.org/whl/cpu
@@ -10,7 +10,7 @@ aiohttp==3.14.5
aiosignal==1.4.0
# via aiohttp
alembic==1.14.0
- # via study-supporter (backend/pyproject.toml)
+ # via -r requirements.in
altair==5.5.0
# via streamlit
annotated-doc==0.0.5
@@ -36,7 +36,7 @@ backoff==2.2.1
# via posthog
bcrypt==4.2.1
# via
- # study-supporter (backend/pyproject.toml)
+ # -r requirements.in
# chromadb
blinker==1.9.0
# via streamlit
@@ -57,7 +57,7 @@ charset-normalizer==3.5.2
chroma-hnswlib==0.7.6
# via chromadb
chromadb==0.5.23
- # via study-supporter (backend/pyproject.toml)
+ # via -r requirements.in
click==8.5.0
# via
# streamlit
@@ -94,7 +94,7 @@ gitpython==3.2.0
google-auth==2.62.0
# via google-genai
google-genai==1.56.0
- # via study-supporter (backend/pyproject.toml)
+ # via -r requirements.in
googleapis-common-protos==1.75.0
# via opentelemetry-exporter-otlp-proto-grpc
greenlet==3.5.6
@@ -169,11 +169,11 @@ narwhals==2.27.1
# scikit-learn
networkx==3.4.2
# via
- # study-supporter (backend/pyproject.toml)
+ # -r requirements.in
# torch
numpy==1.26.4
# via
- # study-supporter (backend/pyproject.toml)
+ # -r requirements.in
# chroma-hnswlib
# chromadb
# onnxruntime
@@ -252,7 +252,7 @@ pillow==11.3.0
# streamlit
posthog==3.7.0
# via
- # study-supporter (backend/pyproject.toml)
+ # -r requirements.in
# chromadb
propcache==0.5.4
# via
@@ -265,7 +265,7 @@ protobuf==5.29.6
# opentelemetry-proto
# streamlit
psycopg2-binary==2.9.10
- # via study-supporter (backend/pyproject.toml)
+ # via -r requirements.in
pyarrow==26.0.0
# via streamlit
pyasn1==0.6.4
@@ -276,7 +276,7 @@ pycparser==3.11
# via cffi
pydantic==2.10.4
# via
- # study-supporter (backend/pyproject.toml)
+ # -r requirements.in
# chromadb
# fastapi
# google-genai
@@ -287,7 +287,7 @@ pydeck==0.9.3
pygments==2.21.0
# via rich
pymupdf==1.25.1
- # via study-supporter (backend/pyproject.toml)
+ # via -r requirements.in
pypika==0.51.1
# via chromadb
pyproject-hooks==1.3.3
@@ -299,7 +299,7 @@ python-dateutil==2.9.0.post0
# posthog
python-dotenv==1.0.1
# via
- # study-supporter (backend/pyproject.toml)
+ # -r requirements.in
# uvicorn
pytz==2026.5
# via pandas
@@ -311,7 +311,7 @@ pyyaml==6.0.3
# transformers
# uvicorn
rank-bm25==0.2.2
- # via study-supporter (backend/pyproject.toml)
+ # via -r requirements.in
referencing==0.37.0
# via
# jsonschema
@@ -320,7 +320,7 @@ regex==2026.9.29
# via transformers
requests==2.32.5
# via
- # study-supporter (backend/pyproject.toml)
+ # -r requirements.in
# google-auth
# google-genai
# huggingface-hub
@@ -349,7 +349,7 @@ scipy==1.17.1
# scikit-learn
# sentence-transformers
sentence-transformers==3.3.1
- # via study-supporter (backend/pyproject.toml)
+ # via -r requirements.in
shellingham==1.5.4
# via typer
six==1.17.0
@@ -363,12 +363,12 @@ sniffio==1.3.1
# via google-genai
sqlalchemy==2.0.36
# via
- # study-supporter (backend/pyproject.toml)
+ # -r requirements.in
# alembic
starlette==1.8.0
# via fastapi
streamlit==1.41.1
- # via study-supporter (backend/pyproject.toml)
+ # via -r requirements.in
sympy==1.13.1
# via torch
tenacity==9.1.4
@@ -386,7 +386,7 @@ toml==0.10.2
# via streamlit
torch==2.5.1+cpu
# via
- # study-supporter (backend/pyproject.toml)
+ # -r requirements.in
# sentence-transformers
tornado==6.5.10
# via streamlit
@@ -398,7 +398,7 @@ tqdm==4.70.1
# transformers
transformers==4.46.3
# via
- # study-supporter (backend/pyproject.toml)
+ # -r requirements.in
# sentence-transformers
typer==0.27.3
# via chromadb
diff --git a/requirements/README.md b/requirements/README.md
deleted file mode 100644
index 3c95ea0..0000000
--- a/requirements/README.md
+++ /dev/null
@@ -1,18 +0,0 @@
-# Dependency locks
-
-`backend/pyproject.toml` is the only source of direct dependency declarations.
-Core installs NumPy, Pydantic and NetworkX; `dev` adds offline test tools and
-lightweight drivers; `runtime` adds Streamlit, Chroma and CPU model execution.
-`dev.txt` supports Python 3.11–3.12. `runtime.txt` targets Linux x86_64/Python 3.11
-and explicitly selects PyTorch CPU wheels. Chroma's PostHog version preserves its
-three-argument telemetry API. No model weights are downloaded at install/build.
-
-Regenerate with uv 0.13.0 from the repository root:
-
-```powershell
-uv pip compile backend/pyproject.toml --extra dev --python-version 3.11 --output-file requirements/dev.txt
-uv pip compile backend/pyproject.toml --extra runtime --python-version 3.11 --python-platform x86_64-unknown-linux-gnu --extra-index-url https://download.pytorch.org/whl/cpu --index-strategy unsafe-best-match --emit-index-url --output-file requirements/runtime.txt
-```
-
-Review any version changes and rerun the offline suite and Docker build. Moving
-these files does not authorize changing runtime versions or stored embeddings.
diff --git a/ruff.toml b/ruff.toml
index 9b6da2a..e26386b 100644
--- a/ruff.toml
+++ b/ruff.toml
@@ -1,10 +1,27 @@
target-version = "py311"
line-length = 100
-include = ["apps/**/*.py", "backend/src/**/*.py", "backend/tests/**/*.py", "backend/migrations/**/*.py", "scripts/**/*.py", "evaluation/**/*.py", "main.py", "eval_test.py"]
+include = [
+ "apps/**/*.py",
+ "backend/src/**/*.py", "backend/tests/**/*.py", "backend/migrations/**/*.py",
+ "scripts/check_import_boundaries.py", "scripts/docker_backup.py", "scripts/docker_smoke.py",
+ "src/auth/*.py", "src/documents/*.py", "src/db/database.py", "src/db/lifecycle.py",
+ "src/memory/progress_db.py", "src/rag/chunker.py", "src/rag/pdf_parser.py",
+ "src/rag/bm25_index.py", "src/rag/hybrid_retriever.py", "src/rag/vector_store.py",
+ "src/rag/embedding_provider.py",
+ "src/graph/schemas.py", "src/llm/errors.py", "src/llm/openai_compatible_client.py",
+ "src/llm/gemini_client.py", "src/llm/multi_provider_llm.py",
+ "src/agent/tools/generate_quiz.py", "src/agent/tools/search_docs.py",
+ "ui/components/auth.py", "ui/components/sidebar.py", "ui/components/chat.py",
+ "ui/components/quiz_arena.py", "main.py", "tests/conftest.py",
+ "tests/test_database_config.py", "tests/test_react_baseline.py",
+ "eval_test.py", "scripts/streamlit_smoke.py",
+ "scripts/model_smoke.py",
+]
[lint]
select = ["E4", "E7", "E9", "F"]
[lint.per-file-ignores]
-# Entrypoint loads dotenv and sets Streamlit page configuration before adapters.
+# Load local dotenv before importing legacy adapters. Remove with explicit bootstrap in P1.
+"main.py" = ["E402"]
"apps/streamlit_legacy/main.py" = ["E402"]
diff --git a/scripts/add_file_hash_column.py b/scripts/add_file_hash_column.py
new file mode 100644
index 0000000..1a353cc
--- /dev/null
+++ b/scripts/add_file_hash_column.py
@@ -0,0 +1,17 @@
+"""Add missing file_hash column to documents table.
+
+Run: python scripts/add_file_hash_column.py
+"""
+import os, sys
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from dotenv import load_dotenv
+load_dotenv()
+
+from sqlalchemy import text
+from src.db.database import engine
+
+with engine.connect() as conn:
+ conn.execute(text("ALTER TABLE documents ADD COLUMN IF NOT EXISTS file_hash VARCHAR"))
+ conn.commit()
+ print("Done: file_hash column added (or already exists)")
diff --git a/scripts/check_import_boundaries.py b/scripts/check_import_boundaries.py
index 73c36c4..95c6732 100644
--- a/scripts/check_import_boundaries.py
+++ b/scripts/check_import_boundaries.py
@@ -14,6 +14,7 @@
"study_supporter.domain.assessment": {"pydantic"},
"study_supporter.ai.graph.algorithms": {"networkx"},
"study_supporter.ai.assessment.json_parsing": {"pydantic"},
+ "study_supporter.application.use_cases.llm_json": {"pydantic"},
}
ALLOWED = {
"domain": {"domain"},
@@ -23,7 +24,7 @@
"orchestration": PURE | {"orchestration"},
"interfaces": {"interfaces", "application", "domain"},
}
-# Pure modules use stdlib plus the exact deterministic dependencies above.
+# Core is stdlib-only today. Allowing only stdlib catches new SDKs automatically.
def violations(source: str, module: str) -> list[str]:
diff --git a/scripts/docker_smoke.py b/scripts/docker_smoke.py
index 7d16870..15abe10 100644
--- a/scripts/docker_smoke.py
+++ b/scripts/docker_smoke.py
@@ -1,148 +1,135 @@
-"""Opt-in Docker acceptance through public application services and real storage."""
+"""Functional Docker smoke with synthetic PDF, mocked quiz/LLM and 1024D fake vectors."""
import argparse
import json
-import os
import uuid
from pathlib import Path
+from unittest.mock import Mock
import fitz
-from study_supporter.bootstrap import ApplicationFactory
-from study_supporter.config import Settings
-from study_supporter.application.contracts.context import AppContext
-from study_supporter.application.contracts.learning import IngestDocumentRequest, QuizRequest
-from study_supporter.application.contracts.retrieval import RetrievalQuery
-from study_supporter.application.ports.llm import ChatResponse
-from study_supporter.infrastructure.llm.factory import ProviderSelection
-from study_supporter.infrastructure.persistence.chroma.note_repository import LongTermMemory
-from study_supporter.domain.errors import DocumentUnsupported, EvidenceNotFound
+from src.auth.auth_service import authenticate_user, register_user
+from src.db.lifecycle import verify_schema
+from src.documents.document_service import (
+ create_document,
+ get_latest_ready_document,
+ update_document_status,
+)
+from src.rag.pdf_parser import parse_pdf
+from src.rag.chunker import (
+ flatten_pages_to_sentences,
+ compute_distances,
+ compute_breakpoints,
+ group_sentences_into_chunks,
+)
+from src.rag.vector_store import VectorStore
+from src.memory.progress_db import ProgressDB
+from src.memory.long_term import LongTermMemory
+from src.agent.tools.generate_quiz import GenerateQuizTool
+from src.llm.llm_adapter import ChatResponse
+from ui.components.quiz_arena import _parse_quiz_from_text
+from study_supporter.domain.errors import DocumentUnsupported
-# Keep the existing marker readable to prove historical volume compatibility.
MARKER = Path("data/p0-smoke.json")
VECTOR = [1.0] + [0.0] * 1023
-class FakeEmbedding:
- dimension = 1024
- model_id = "BAAI/bge-m3"
-
- def embed(self, texts, task_type):
- return [list(VECTOR) for _ in texts]
-
-
-class FakeLLM:
- def chat(self, messages, **kwargs):
- if not kwargs.get("system_prompt"):
- return ChatResponse(
- text=json.dumps(
- {
- "questions": [
- {
- "question": "Q?",
- "options": ["a", "b", "c", "d"],
- "correct_answer_index": 1,
- "explanation": "fixture",
- }
- ]
- }
- )
- )
- if "Observation:" in messages[-1]["content"]:
- return ChatResponse(text="Final Answer: First sentence. [fixture.pdf, page 1]")
- return ChatResponse(
- text='Action: search_docs\nAction Input: {"query": "First sentence", "top_k": 1}'
- )
-
-
-def fixture_pdf(blank=False):
- with fitz.open() as pdf:
- page = pdf.new_page()
- if not blank:
- page.insert_text((72, 72), "First sentence. Second sentence.")
- return pdf.tobytes()
-
-
-def verify(services, state):
- a, b = AppContext(str(state["a"])), AppContext(str(state["b"]))
- assert services.authentication.authenticate(state["username"], state["password"]) == a
- doc = services.document_repository.latest(a.user_id)
+def verify(state):
+ a, b = state["a"], state["b"]
+ assert authenticate_user(state["username"], state["password"]) == a
+ doc = get_latest_ready_document(a)
assert doc and doc["id"] == state["document_id"]
- assert services.document_repository.latest(b.user_id) is None
- with_context = AppContext(a.user_id, (str(doc["id"]),))
- evidence = services.retriever().execute(
- RetrievalQuery(a.user_id, with_context.active_document_ids, "First", 3)
- )
- assert evidence and evidence[0].source == "fixture.pdf"
- try:
- services.open_document(b, doc["id"])
- except EvidenceNotFound:
- pass
- else:
- raise AssertionError("Cross-user document access accepted")
- session = services.open_document(a, doc["id"])
- assert session and session.context == with_context
- answer = session.answer("First sentence?")
- assert answer.answer and answer.evidences and answer.trace_id
- assert session.progress()["total_attempts"] == 1
- assert services.progress_repository.get_summary(b.user_id)["total_attempts"] == 0
- store = services.vector_store(doc)
+ assert get_latest_ready_document(b) is None
+ store = VectorStore(collection_name=doc["chroma_collection_name"])
assert store.count() == state["chunk_count"]
+ result = store.documents.query(query_embeddings=[VECTOR], n_results=1)
+ assert result["ids"][0]
+ assert result["metadatas"][0][0]["source"] == "fixture.pdf"
+ progress = ProgressDB()
+ assert progress.get_summary(str(a))["total_attempts"] == 1
+ assert progress.get_summary(str(b))["total_attempts"] == 0
notes = LongTermMemory(store, lambda _: VECTOR)
- assert notes.search_notes(a.user_id, "question") == ["Synthetic note A"]
- assert notes.search_notes(b.user_id, "question") == []
+ assert notes.search_notes(str(a), "question") == ["Synthetic note A"]
+ assert notes.search_notes(str(b), "question") == []
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("action", choices=["seed", "verify"])
args = parser.parse_args()
- with ApplicationFactory(
- Settings.from_mapping(os.environ),
- embedding=FakeEmbedding(),
- provider_factory=lambda settings, mode: ProviderSelection(FakeLLM(), "ollama"),
- ) as services:
- services.verify_schema()
- if args.action == "seed":
- if MARKER.exists():
- parser.error("Marker exists; use verify or a fresh disposable project")
- suffix, password = uuid.uuid4().hex[:12], uuid.uuid4().hex
- username = f"smoke-a-{suffix}"
- a = services.authentication.register(username, password)
- b = services.authentication.register(f"smoke-b-{suffix}", uuid.uuid4().hex)
- request = IngestDocumentRequest(a, "fixture.pdf", fixture_pdf())
- events = []
- result = services.ingestion.execute(request, events.append)
- assert services.ingestion.execute(request).reused
- assert events[-1].stage.value == "READY"
- assert len({event.trace_id for event in events}) == 1
- session = services.open_document(a, result.document_id)
- quiz = session.generate_quiz(QuizRequest(session.context, 1, "fixture"))
- assert len(quiz) == 1 and quiz[0]["correct_index"] == 1
- assert session.submit_quiz(quiz[0], 1).is_correct
- session.save_note("Synthetic note A")
+ verify_schema()
+ if args.action == "seed":
+ if MARKER.exists():
+ parser.error("Marker already exists; use verify or a fresh disposable project")
+ suffix = uuid.uuid4().hex[:12]
+ username, password = f"p0-a-{suffix}", uuid.uuid4().hex
+ a = register_user(username, password)
+ b = register_user(f"p0-b-{suffix}", uuid.uuid4().hex)
+ path = Path("data/fixture.pdf")
+ with fitz.open() as pdf:
+ pdf.new_page().insert_text((72, 72), "First sentence. Second sentence.")
+ pdf.save(path)
+ try:
+ pages = parse_pdf(str(path)).pages
+ sentences = flatten_pages_to_sentences(pages)
+ for sentence in sentences:
+ sentence.embedding = VECTOR
+ chunks = group_sentences_into_chunks(
+ sentences, compute_breakpoints(sentences, compute_distances(sentences))
+ )
+ finally:
+ path.unlink(missing_ok=True)
+ doc_id, collection = create_document(a, "fixture.pdf")
+ store = VectorStore(collection_name=collection)
+ store.add_chunks(chunks, [VECTOR for _ in chunks])
+ update_document_status(doc_id, "ready", page_count=1, chunk_count=len(chunks), user_id=a)
+ llm = Mock()
+ llm.chat.return_value = ChatResponse(
+ text=json.dumps(
+ {
+ "questions": [
+ {
+ "question": "Q?",
+ "options": ["a", "b", "c", "d"],
+ "correct_answer_index": 1,
+ "explanation": "fixture",
+ }
+ ]
+ }
+ )
+ )
+ quiz = _parse_quiz_from_text(GenerateQuizTool(llm).run(chunks[0].text))
+ assert quiz and quiz[0]["correct_index"] == 1
+ ProgressDB().record_attempt(str(a), "fixture", quiz[0]["question"], True, doc_id)
+ LongTermMemory(store, lambda _: VECTOR).save_note(str(a), "Synthetic note A")
+ with fitz.open() as pdf:
+ pdf.new_page()
+ pdf.save(path)
+ try:
try:
- services.ingestion.execute(IngestDocumentRequest(a, "blank.pdf", fixture_pdf(True)))
+ parse_pdf(str(path))
except DocumentUnsupported:
pass
else:
raise AssertionError("Blank PDF accepted")
- state = {
- "a": int(a.user_id),
- "b": int(b.user_id),
- "username": username,
- "password": password,
- "document_id": result.document_id,
- "chunk_count": result.chunk_count,
- }
- MARKER.write_text(json.dumps(state), encoding="utf-8")
- else:
- state = json.loads(MARKER.read_text(encoding="utf-8"))
- verify(services, state)
+ finally:
+ path.unlink(missing_ok=True)
+ state = {
+ "a": a,
+ "b": b,
+ "username": username,
+ "password": password,
+ "document_id": doc_id,
+ "chunk_count": len(chunks),
+ }
+ MARKER.write_text(json.dumps(state), encoding="utf-8")
+ else:
+ state = json.loads(MARKER.read_text(encoding="utf-8"))
+ verify(state)
print(
- "PASS: canonical auth/ingestion/retrieval/chat/quiz/notes/progress, persisted data and A/B isolation"
+ "PASS: SQL/auth, PDF/chunk provenance, persistent Chroma, quiz/progress, A/B ownership and notes"
)
- print("Synthetic embeddings/LLM; real model and browser checks are separate")
+ print("Synthetic embeddings and mocked LLM; BGE/Ollama/browser E2E remain separate checks")
if __name__ == "__main__":
diff --git a/scripts/model_smoke.py b/scripts/model_smoke.py
index ad7c158..530a429 100644
--- a/scripts/model_smoke.py
+++ b/scripts/model_smoke.py
@@ -1,66 +1,105 @@
-"""Opt-in real BGE-M3/Ollama execution through the canonical application facade."""
+"""Opt-in real BGE-M3/Ollama smoke in an isolated synthetic account."""
import json
-import os
import uuid
-from dataclasses import replace
from pathlib import Path
import fitz
-from study_supporter.bootstrap import ApplicationFactory
-from study_supporter.config import Settings
-from study_supporter.application.contracts.learning import IngestDocumentRequest, QuizRequest
-from study_supporter.application.contracts.retrieval import RetrievalQuery
+from src.agent.orchestrator import ReActOrchestrator
+from src.agent.tools.generate_quiz import GenerateQuizTool
+from src.agent.tools.search_docs import SearchDocsTool
+from src.auth.auth_service import authenticate_user, register_user
+from src.db.lifecycle import verify_schema
+from src.documents.document_service import (
+ create_document,
+ get_latest_ready_document,
+ update_document_status,
+)
+from src.llm.ollama_client import OllamaClient
+from src.memory.progress_db import ProgressDB
+from src.rag.bm25_index import BM25Index
+from src.rag.chunker import (
+ compute_breakpoints,
+ compute_distances,
+ embed_sentences,
+ flatten_pages_to_sentences,
+ group_sentences_into_chunks,
+)
+from src.rag.embedder import embed_chunks
+from src.rag.embedding_provider import LocalEmbeddingProvider
+from src.rag.hybrid_retriever import hybrid_search
+from src.rag.pdf_parser import parse_pdf
+from src.rag.vector_store import VectorStore
+from ui.components.quiz_arena import _parse_quiz_from_text
def main():
- settings = replace(Settings.from_mapping(os.environ), ollama_model="qwen3:1.7b")
- with ApplicationFactory(settings) as services:
- services.verify_schema()
- suffix, password = uuid.uuid4().hex[:12], uuid.uuid4().hex
- username = f"model-smoke-{suffix}"
- context = services.authentication.register(username, password)
- assert services.authentication.authenticate(username, password) == context
- content = "A computer network connects devices to exchange data. A router forwards data between networks. A switch connects devices within a local network."
- filename = f"model-fixture-{suffix}.pdf"
- with fitz.open() as pdf:
- pdf.new_page().insert_textbox(fitz.Rect(72, 72, 500, 500), content)
- uploaded = pdf.tobytes()
- document = services.ingestion.execute(IngestDocumentRequest(context, filename, uploaded))
- session = services.open_document(context, document.document_id, mode="ollama")
- evidence = services.retriever().execute(
- RetrievalQuery(
- context.user_id, session.context.active_document_ids, "What does a router do?", 1
- )
+ verify_schema()
+ provider = LocalEmbeddingProvider()
+ suffix, password = uuid.uuid4().hex[:12], uuid.uuid4().hex
+ username = f"model-smoke-{suffix}"
+ user_id = register_user(username, password)
+ assert authenticate_user(username, password) == user_id
+ path = Path(f"data/model-fixture-{suffix}.pdf")
+ content = "A computer network connects devices to exchange data. A router forwards data between networks. A switch connects devices within a local network."
+ with fitz.open() as pdf:
+ pdf.new_page().insert_textbox(fitz.Rect(72, 72, 500, 500), content)
+ pdf.save(path)
+ try:
+ pages = parse_pdf(str(path)).pages
+ sentences = embed_sentences(flatten_pages_to_sentences(pages), provider)
+ chunks = group_sentences_into_chunks(
+ sentences, compute_breakpoints(sentences, compute_distances(sentences))
)
- assert evidence and evidence[0].source == filename
- assert len(services.embedding.embed(["router"], "RETRIEVAL_QUERY")[0]) == 1024
- answer = session.answer(
+ assert chunks
+ vectors = embed_chunks(chunks, provider)
+ assert len(vectors[0]) == 1024
+ document_id, collection = create_document(user_id, path.name)
+ store = VectorStore(collection_name=collection)
+ store.add_chunks(chunks, vectors)
+ update_document_status(
+ document_id, "ready", page_count=1, chunk_count=len(chunks), user_id=user_id
+ )
+ bm25 = BM25Index(chunks)
+
+ def embed_query(text):
+ return provider.embed([text], "RETRIEVAL_QUERY")[0]
+
+ retrieved = hybrid_search("What does a router do?", store, bm25, embed_query, top_k=1)
+ assert retrieved and retrieved[0].source == path.name
+ llm = OllamaClient(model="qwen3:1.7b")
+ search = SearchDocsTool(store, bm25, embed_query, document_id=str(document_id))
+ result = ReActOrchestrator(llm, [search]).run(
"Use search_docs to explain what a router does, based only on the uploaded document."
)
- assert answer.answer.strip() and answer.evidences
- quiz = session.generate_quiz(QuizRequest(session.context, 1, "networking"))
- assert len(quiz) == 1
- assert session.submit_quiz(quiz[0], quiz[0]["correct_index"]).is_correct
- assert session.progress()["total_attempts"] == 1
- Path("data/real-model-smoke.json").write_text(
+ assert result.final_answer.strip() and search.last_evidence
+ quiz = _parse_quiz_from_text(GenerateQuizTool(llm).run(content, num_questions=1))
+ assert quiz and len(quiz) == 1
+ ProgressDB().record_attempt(
+ str(user_id), "networking", quiz[0]["question"], True, document_id
+ )
+ assert ProgressDB().get_summary(str(user_id))["total_attempts"] == 1
+ assert get_latest_ready_document(user_id)["id"] == document_id
+ Path("data/p0-real-model-smoke.json").write_text(
json.dumps(
{
- "user_id": context.user_id,
- "document_id": document.document_id,
- "chunk_count": document.chunk_count,
- "trace_id": answer.trace_id,
+ "user_id": user_id,
+ "document_id": document_id,
+ "collection": collection,
+ "chunk_count": len(chunks),
}
),
encoding="utf-8",
)
- print(
- "PASS: real BGE-M3 1024D ingestion/retrieval, Ollama ReAct/evidence/quiz, persisted progress"
- )
- print(
- "Synthetic account service execution; browser acceptance and quality benchmarks are separate"
- )
+ print(
+ "PASS: real BGE-M3 1024D PDF ingestion, hybrid retrieval, Ollama ReAct/evidence, valid quiz and persisted progress"
+ )
+ print(
+ "Provider smoke is synthetic-account service execution, not browser E2E or a quality benchmark"
+ )
+ finally:
+ path.unlink(missing_ok=True)
if __name__ == "__main__":
diff --git a/scripts/patch_graph_builder.py b/scripts/patch_graph_builder.py
new file mode 100644
index 0000000..e30d4db
--- /dev/null
+++ b/scripts/patch_graph_builder.py
@@ -0,0 +1,27 @@
+from pathlib import Path
+
+path = Path('src/graph/graph_builder.py')
+text = path.read_text(encoding='utf-8', errors='replace')
+print('----- FILE START -----')
+print(text)
+print('----- END PREVIEW -----')
+
+idx = text.find('def build_concept_graph')
+if idx == -1:
+ raise SystemExit('function definition not found')
+
+prefix = text[:idx]
+new_func = '''def build_concept_graph(content: str, llm: LLMAdapter) -> ConceptGraph:
+ prompt = GRAPH_EXTRACTION_PROMPT.format(content=content)
+
+ response = llm.chat([{"role": "user", "content": prompt}])
+ try:
+ return parse_llm_model(response.text, ConceptGraph)
+ except Exception as e:
+ raise RuntimeError(
+ f"Graph extraction failed: {e}. Model response: {response.text}"
+ ) from e
+'''
+text = prefix + new_func
+path.write_text(text, encoding='utf-8')
+print('rewrote function')
diff --git a/scripts/streamlit_smoke.py b/scripts/streamlit_smoke.py
index a67dd81..0c6096c 100644
--- a/scripts/streamlit_smoke.py
+++ b/scripts/streamlit_smoke.py
@@ -4,18 +4,15 @@
from streamlit.testing.v1 import AppTest
-import os
-from study_supporter.bootstrap import ApplicationFactory
-from study_supporter.config import Settings
+from src.auth.auth_service import register_user
def main():
marker = uuid.uuid4().hex[:12]
password = uuid.uuid4().hex
a, b = f"ui-a-{marker}", f"ui-b-{marker}"
- with ApplicationFactory(Settings.from_mapping(os.environ)) as services:
- b_id = services.authentication.register(b, password).user_id
- app = AppTest.from_file("apps/streamlit_legacy/main.py", default_timeout=30).run()
+ b_id = register_user(b, password)
+ app = AppTest.from_file("main.py", default_timeout=30).run()
assert not app.exception
app.text_input(key="register_username").set_value(a)
app.text_input(key="register_password").set_value(password)
diff --git a/scripts/test_setup.py b/scripts/test_setup.py
new file mode 100644
index 0000000..adca4c6
--- /dev/null
+++ b/scripts/test_setup.py
@@ -0,0 +1,25 @@
+# scripts/test_setup.py
+import os
+from dotenv import load_dotenv
+from google import genai
+from google.genai.types import EmbedContentConfig
+
+load_dotenv()
+client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))
+
+try:
+ result = client.models.embed_content(
+ model="gemini-embedding-001", # <-- đổi lại đúng model này
+ contents="Xin chào, đây là test embedding.",
+ config=EmbedContentConfig(
+ task_type="RETRIEVAL_DOCUMENT",
+ output_dimensionality=768,
+ ),
+ )
+ vector = result.embeddings[0].values
+ print("✅ Kết nối API thành công!")
+ print("Vector length:", len(vector))
+ print("5 giá trị đầu:", vector[:5])
+except Exception as e:
+ print("❌ Lỗi gọi API:")
+ print(e)
\ No newline at end of file
diff --git a/src/__init__.py b/src/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/src/agent/__init__.py b/src/agent/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/src/agent/orchestrator.py b/src/agent/orchestrator.py
new file mode 100644
index 0000000..2507202
--- /dev/null
+++ b/src/agent/orchestrator.py
@@ -0,0 +1,4 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+import importlib
+import sys
+sys.modules[__name__] = importlib.import_module("study_supporter.orchestration.legacy_react.orchestrator")
diff --git a/src/agent/prompt_templates.py b/src/agent/prompt_templates.py
new file mode 100644
index 0000000..8be7e3c
--- /dev/null
+++ b/src/agent/prompt_templates.py
@@ -0,0 +1,4 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+import importlib
+import sys
+sys.modules[__name__] = importlib.import_module("study_supporter.orchestration.legacy_react.prompt_templates")
diff --git a/docs/archive/legacy-notes/src/agent/sprint3_notes.md b/src/agent/sprint3_notes.md
similarity index 100%
rename from docs/archive/legacy-notes/src/agent/sprint3_notes.md
rename to src/agent/sprint3_notes.md
diff --git a/src/agent/state.py b/src/agent/state.py
new file mode 100644
index 0000000..65e4ee7
--- /dev/null
+++ b/src/agent/state.py
@@ -0,0 +1,4 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+import importlib
+import sys
+sys.modules[__name__] = importlib.import_module("study_supporter.orchestration.legacy_react.state")
diff --git a/src/agent/tools/__init__.py b/src/agent/tools/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/src/agent/tools/base.py b/src/agent/tools/base.py
new file mode 100644
index 0000000..0d447a0
--- /dev/null
+++ b/src/agent/tools/base.py
@@ -0,0 +1,4 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+import importlib
+import sys
+sys.modules[__name__] = importlib.import_module("study_supporter.orchestration.legacy_react.tools.base")
diff --git a/src/agent/tools/generate_quiz.py b/src/agent/tools/generate_quiz.py
new file mode 100644
index 0000000..01cd9bf
--- /dev/null
+++ b/src/agent/tools/generate_quiz.py
@@ -0,0 +1,6 @@
+import importlib
+import sys
+
+sys.modules[__name__] = importlib.import_module(
+ "study_supporter.orchestration.legacy_react.tools.generate_quiz"
+)
diff --git a/src/agent/tools/get_progress.py b/src/agent/tools/get_progress.py
new file mode 100644
index 0000000..cf027f4
--- /dev/null
+++ b/src/agent/tools/get_progress.py
@@ -0,0 +1,4 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+import importlib
+import sys
+sys.modules[__name__] = importlib.import_module("study_supporter.orchestration.legacy_react.tools.get_progress")
diff --git a/src/agent/tools/save_note.py b/src/agent/tools/save_note.py
new file mode 100644
index 0000000..e95ebf4
--- /dev/null
+++ b/src/agent/tools/save_note.py
@@ -0,0 +1,4 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+import importlib
+import sys
+sys.modules[__name__] = importlib.import_module("study_supporter.orchestration.legacy_react.tools.save_note")
diff --git a/src/agent/tools/search_docs.py b/src/agent/tools/search_docs.py
new file mode 100644
index 0000000..212d9f5
--- /dev/null
+++ b/src/agent/tools/search_docs.py
@@ -0,0 +1,6 @@
+import importlib
+import sys
+
+sys.modules[__name__] = importlib.import_module(
+ "study_supporter.infrastructure.retrieval.legacy_tools"
+)
diff --git a/src/auth/auth_service.py b/src/auth/auth_service.py
new file mode 100644
index 0000000..e3b2aa5
--- /dev/null
+++ b/src/auth/auth_service.py
@@ -0,0 +1,8 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+
+import importlib
+import sys
+
+sys.modules[__name__] = importlib.import_module(
+ "study_supporter.infrastructure.persistence.sqlalchemy.auth_repository"
+)
diff --git a/src/auth/session.py b/src/auth/session.py
new file mode 100644
index 0000000..ffb1782
--- /dev/null
+++ b/src/auth/session.py
@@ -0,0 +1 @@
+from apps.streamlit_legacy.session import reset_session_on_logout as reset_session_on_logout
diff --git a/src/config.py b/src/config.py
new file mode 100644
index 0000000..cf2ce79
--- /dev/null
+++ b/src/config.py
@@ -0,0 +1,10 @@
+# src/config.py (tạo mới nếu chưa có, dùng chung cho toàn project)
+import os
+import streamlit as st
+
+def get_api_key(key_name: str) -> str | None:
+ # Ưu tiên st.secrets khi chạy trên Streamlit Cloud
+ try:
+ return st.secrets[key_name]
+ except (KeyError, FileNotFoundError):
+ return os.getenv(key_name)
\ No newline at end of file
diff --git a/src/db/database.py b/src/db/database.py
new file mode 100644
index 0000000..68d5cb5
--- /dev/null
+++ b/src/db/database.py
@@ -0,0 +1,8 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+
+import importlib
+import sys
+
+sys.modules[__name__] = importlib.import_module(
+ "study_supporter.infrastructure.persistence.sqlalchemy.database"
+)
diff --git a/src/db/lifecycle.py b/src/db/lifecycle.py
new file mode 100644
index 0000000..782c775
--- /dev/null
+++ b/src/db/lifecycle.py
@@ -0,0 +1,8 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+
+import importlib
+import sys
+
+sys.modules[__name__] = importlib.import_module(
+ "study_supporter.infrastructure.persistence.sqlalchemy.lifecycle"
+)
diff --git a/src/db/models.py b/src/db/models.py
new file mode 100644
index 0000000..071d2c6
--- /dev/null
+++ b/src/db/models.py
@@ -0,0 +1,4 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+import importlib
+import sys
+sys.modules[__name__] = importlib.import_module("study_supporter.infrastructure.persistence.sqlalchemy.models")
diff --git a/src/documents/document_service.py b/src/documents/document_service.py
new file mode 100644
index 0000000..1619fb8
--- /dev/null
+++ b/src/documents/document_service.py
@@ -0,0 +1,8 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+
+import importlib
+import sys
+
+sys.modules[__name__] = importlib.import_module(
+ "study_supporter.infrastructure.persistence.sqlalchemy.document_repository"
+)
diff --git a/src/documents/upload_validation.py b/src/documents/upload_validation.py
new file mode 100644
index 0000000..c7b4a06
--- /dev/null
+++ b/src/documents/upload_validation.py
@@ -0,0 +1,6 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+
+import importlib
+import sys
+
+sys.modules[__name__] = importlib.import_module("study_supporter.domain.upload_validation")
diff --git a/src/eval/__init__.py b/src/eval/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/evaluation/eval_runner.py b/src/eval/eval_runner.py
similarity index 52%
rename from evaluation/eval_runner.py
rename to src/eval/eval_runner.py
index bef2e58..c4af418 100644
--- a/evaluation/eval_runner.py
+++ b/src/eval/eval_runner.py
@@ -1,7 +1,7 @@
import json
import time
-from evaluation.rag_only import answer_with_rag_only
-from study_supporter.infrastructure.retrieval.hybrid_adapter import hybrid_search
+from src.eval.rag_only import answer_with_rag_only
+from src.rag.hybrid_retriever import hybrid_search
def load_eval_dataset(path: str = "data/eval_dataset.json") -> list[dict]:
@@ -25,33 +25,29 @@ def run_eval(dataset, store, bm25_index, embed_query_fn, llm, orchestrator, top_
t0 = time.time()
rag_chunks = hybrid_search(question, store, bm25_index, embed_query_fn, top_k=top_k)
- rag_answer = answer_with_rag_only(
- question, store, bm25_index, embed_query_fn, llm, top_k=top_k
- )
+ rag_answer = answer_with_rag_only(question, store, bm25_index, embed_query_fn, llm, top_k=top_k)
t1 = time.time()
state = orchestrator.run(question, conversation_history=history_text)
t2 = time.time()
- results.append(
- {
- "id": item["id"],
- "category": category,
- "question": question,
- "reference_answer": item.get("reference_answer"),
- "rag_only": {
- "answer": rag_answer,
- "retrieved_chunk_ids": [c.chunk_id for c in rag_chunks],
- "time_sec": round(t1 - t0, 2),
- },
- "agent_rag": {
- "answer": state.final_answer,
- "iterations": state.iteration,
- "tools_used": [e.tool_name for e in state.scratchpad if e.type == "action"],
- "time_sec": round(t2 - t1, 2),
- },
- }
- )
+ results.append({
+ "id": item["id"],
+ "category": category,
+ "question": question,
+ "reference_answer": item.get("reference_answer"),
+ "rag_only": {
+ "answer": rag_answer,
+ "retrieved_chunk_ids": [c.chunk_id for c in rag_chunks],
+ "time_sec": round(t1 - t0, 2),
+ },
+ "agent_rag": {
+ "answer": state.final_answer,
+ "iterations": state.iteration,
+ "tools_used": [e.tool_name for e in state.scratchpad if e.type == "action"],
+ "time_sec": round(t2 - t1, 2),
+ },
+ })
conversation_log.append(f"Q: {question}\nA: {state.final_answer}")
@@ -60,4 +56,4 @@ def run_eval(dataset, store, bm25_index, embed_query_fn, llm, orchestrator, top_
def save_results(results: list[dict], path: str = "data/eval_results.json") -> None:
with open(path, "w", encoding="utf-8") as f:
- json.dump(results, f, ensure_ascii=False, indent=2)
+ json.dump(results, f, ensure_ascii=False, indent=2)
\ No newline at end of file
diff --git a/evaluation/llm_judge.py b/src/eval/llm_judge.py
similarity index 80%
rename from evaluation/llm_judge.py
rename to src/eval/llm_judge.py
index 82e0a9e..7d59c33 100644
--- a/evaluation/llm_judge.py
+++ b/src/eval/llm_judge.py
@@ -1,12 +1,12 @@
from pydantic import BaseModel
-from study_supporter.application.ports.llm import LLMAdapter
-from study_supporter.ai.assessment.json_parsing import parse_llm_model
+from src.llm.llm_adapter import LLMAdapter
+from src.llm.json_utils import parse_llm_model
class JudgeScore(BaseModel):
- faithfulness: int # 1-5: có bám sát đáp án tham chiếu, không bịa đặt
- relevance: int # 1-5: có đúng trọng tâm câu hỏi
- reasoning: str # giải thích ngắn vì sao chấm điểm như vậy
+ faithfulness: int # 1-5: có bám sát đáp án tham chiếu, không bịa đặt
+ relevance: int # 1-5: có đúng trọng tâm câu hỏi
+ reasoning: str # giải thích ngắn vì sao chấm điểm như vậy
JUDGE_PROMPT = """Bạn là người chấm điểm khách quan cho hệ thống AI trợ giảng. Đánh giá câu trả lời sau theo 2 tiêu chí, mỗi tiêu chí từ 1-5 điểm:
@@ -43,4 +43,4 @@ def judge_answer(
try:
return parse_llm_model(response.text, JudgeScore)
except Exception as e:
- return JudgeScore(faithfulness=0, relevance=0, reasoning=f"Lỗi parse judge output: {e}")
+ return JudgeScore(faithfulness=0, relevance=0, reasoning=f"Lỗi parse judge output: {e}")
\ No newline at end of file
diff --git a/evaluation/metrics.py b/src/eval/metrics.py
similarity index 85%
rename from evaluation/metrics.py
rename to src/eval/metrics.py
index 8487a83..106d642 100644
--- a/evaluation/metrics.py
+++ b/src/eval/metrics.py
@@ -5,10 +5,8 @@
def compute_summary(judged_results: list[dict]) -> dict:
summary = {
- "overall": {
- "rag_only": {"faithfulness": [], "relevance": [], "parse_errors": 0},
- "agent_rag": {"faithfulness": [], "relevance": [], "parse_errors": 0},
- },
+ "overall": {"rag_only": {"faithfulness": [], "relevance": [], "parse_errors": 0},
+ "agent_rag": {"faithfulness": [], "relevance": [], "parse_errors": 0}},
"by_category": {},
}
@@ -52,17 +50,14 @@ def _finalize(d):
"by_category": {cat: _finalize(d) for cat, d in summary["by_category"].items()},
}
-
def print_summary_table(summary: dict) -> None:
print("=" * 60)
print("TỔNG QUAN (toàn bộ câu hỏi)")
print("=" * 60)
for pipeline, stats in summary["overall"].items():
- print(
- f"{pipeline:12s} | Faithfulness: {stats['avg_faithfulness']} | "
- f"Relevance: {stats['avg_relevance']} | n_scored={stats['n_scored']} | "
- f"parse_errors={stats['parse_errors']}"
- )
+ print(f"{pipeline:12s} | Faithfulness: {stats['avg_faithfulness']} | "
+ f"Relevance: {stats['avg_relevance']} | n_scored={stats['n_scored']} | "
+ f"parse_errors={stats['parse_errors']}")
print("\n" + "=" * 60)
print("THEO CATEGORY")
@@ -70,18 +65,14 @@ def print_summary_table(summary: dict) -> None:
for category, pipelines in summary["by_category"].items():
print(f"\n--- {category} ---")
for pipeline, stats in pipelines.items():
- print(
- f" {pipeline:12s} | Faithfulness: {stats['avg_faithfulness']} | "
- f"Relevance: {stats['avg_relevance']} | n_scored={stats['n_scored']} | "
- f"parse_errors={stats['parse_errors']}"
- )
-
+ print(f" {pipeline:12s} | Faithfulness: {stats['avg_faithfulness']} | "
+ f"Relevance: {stats['avg_relevance']} | n_scored={stats['n_scored']} | "
+ f"parse_errors={stats['parse_errors']}")
def cosine_similarity(a: list[float], b: list[float]) -> float:
a, b = np.array(a), np.array(b)
return float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b)))
-
def compute_similarity_score(reference_answer: str | None, answer: str, provider) -> float | None:
if not reference_answer:
return None
@@ -89,7 +80,6 @@ def compute_similarity_score(reference_answer: str | None, answer: str, provider
ans_emb = provider.embed([answer], task_type="SEMANTIC_SIMILARITY")[0]
return round(cosine_similarity(ref_emb, ans_emb), 3)
-
def compute_similarity_for_results(results: list[dict], provider) -> list[dict]:
"""
Tính cosine similarity giữa answer và reference_answer cho mỗi câu
@@ -144,7 +134,6 @@ def print_similarity_table(summary: dict) -> None:
for pipeline, avg in pipelines.items():
print(f" {pipeline:12s} | avg similarity: {avg}")
-
if __name__ == "__main__":
with open("data/eval_results_judged.json", encoding="utf-8") as f:
judged_results = json.load(f)
@@ -154,8 +143,7 @@ def print_similarity_table(summary: dict) -> None:
print_summary_table(summary)
# --- Phần cosine similarity (mới, không tốn quota) ---
- from study_supporter.infrastructure.embeddings.providers import LocalEmbeddingProvider
-
+ from src.rag.embedding_provider import LocalEmbeddingProvider
provider = LocalEmbeddingProvider()
judged_results = compute_similarity_for_results(judged_results, provider)
@@ -167,9 +155,4 @@ def print_similarity_table(summary: dict) -> None:
json.dump(judged_results, f, ensure_ascii=False, indent=2)
with open("data/eval_summary.json", "w", encoding="utf-8") as f:
- json.dump(
- {"llm_judge": summary, "similarity": similarity_summary},
- f,
- ensure_ascii=False,
- indent=2,
- )
+ json.dump({"llm_judge": summary, "similarity": similarity_summary}, f, ensure_ascii=False, indent=2)
\ No newline at end of file
diff --git a/evaluation/rag_only.py b/src/eval/rag_only.py
similarity index 85%
rename from evaluation/rag_only.py
rename to src/eval/rag_only.py
index 28df410..cf6d97a 100644
--- a/evaluation/rag_only.py
+++ b/src/eval/rag_only.py
@@ -1,5 +1,5 @@
-from study_supporter.infrastructure.retrieval.hybrid_adapter import hybrid_search
-from study_supporter.application.ports.llm import LLMAdapter
+from src.rag.hybrid_retriever import hybrid_search
+from src.llm.llm_adapter import LLMAdapter
RAG_ONLY_PROMPT_TEMPLATE = """Bạn là một AI Trợ Giảng. Dựa trên các đoạn tài liệu sau, hãy trả lời câu hỏi của học sinh một cách chính xác và đầy đủ. Nếu tài liệu không có thông tin liên quan, hãy nói rõ thay vì bịa đặt.
@@ -36,9 +36,10 @@ def answer_with_rag_only(
context = "(Không tìm thấy tài liệu liên quan.)"
else:
context = "\n\n".join(
- f"[Nguồn: {c.source}, trang {c.page_start}-{c.page_end}]\n{c.text}" for c in chunks
+ f"[Nguồn: {c.source}, trang {c.page_start}-{c.page_end}]\n{c.text}"
+ for c in chunks
)
prompt = RAG_ONLY_PROMPT_TEMPLATE.format(context=context, question=question)
response = llm.chat([{"role": "user", "content": prompt}])
- return response.text
+ return response.text
\ No newline at end of file
diff --git a/evaluation/run_judge.py b/src/eval/run_judge.py
similarity index 74%
rename from evaluation/run_judge.py
rename to src/eval/run_judge.py
index a0116d3..c1e314f 100644
--- a/evaluation/run_judge.py
+++ b/src/eval/run_judge.py
@@ -1,6 +1,7 @@
import json
-from evaluation.llm_judge import judge_answer
-from study_supporter.infrastructure.llm.ollama_client import OllamaClient
+import time
+from src.eval.llm_judge import judge_answer
+from src.llm.ollama_client import OllamaClient
def run_judge_on_results(results: list[dict], judge_llm) -> list[dict]:
@@ -18,10 +19,8 @@ def run_judge_on_results(results: list[dict], judge_llm) -> list[dict]:
agent_score = judge_answer(question, reference, item["agent_rag"]["answer"], judge_llm)
item["agent_rag"]["score"] = agent_score.model_dump()
- print(
- f"[{item['id']}] RAG-only: F={rag_score.faithfulness} R={rag_score.relevance} | "
- f"Agent+RAG: F={agent_score.faithfulness} R={agent_score.relevance}"
- )
+ print(f"[{item['id']}] RAG-only: F={rag_score.faithfulness} R={rag_score.relevance} | "
+ f"Agent+RAG: F={agent_score.faithfulness} R={agent_score.relevance}")
return results
@@ -32,16 +31,18 @@ def run_judge_on_results(results: list[dict], judge_llm) -> list[dict]:
# judge_llm nên là GeminiClient — model đủ tốt để chấm điểm đáng tin,
# KHÔNG dùng Ollama 1.5B để chấm (model quá yếu, điểm số sẽ không đáng tin cậy)
-
+ from google import genai
+ from src.llm.gemini_client import GeminiClient
+ import os
from dotenv import load_dotenv
load_dotenv()
# judge_llm = GeminiClient(genai.Client(api_key=os.getenv("GEMINI_API_KEY")))
- judge_llm = OllamaClient(model="qwen3:1.7b")
+ judge_llm = OllamaClient(model='qwen3:1.7b')
judged_results = run_judge_on_results(results, judge_llm)
with open("data/eval_results_judged.json", "w", encoding="utf-8") as f:
json.dump(judged_results, f, ensure_ascii=False, indent=2)
- print("\nĐã lưu data/eval_results_judged.json")
+ print("\nĐã lưu data/eval_results_judged.json")
\ No newline at end of file
diff --git a/docs/archive/legacy-notes/src/eval/sprint5_notes.md b/src/eval/sprint5_notes.md
similarity index 100%
rename from docs/archive/legacy-notes/src/eval/sprint5_notes.md
rename to src/eval/sprint5_notes.md
diff --git a/src/graph/__init__.py b/src/graph/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/src/graph/graph_algorithms.py b/src/graph/graph_algorithms.py
new file mode 100644
index 0000000..ba4efc2
--- /dev/null
+++ b/src/graph/graph_algorithms.py
@@ -0,0 +1,4 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+import importlib
+import sys
+sys.modules[__name__] = importlib.import_module("study_supporter.ai.graph.algorithms")
diff --git a/src/graph/graph_builder.py b/src/graph/graph_builder.py
new file mode 100644
index 0000000..4fb5703
--- /dev/null
+++ b/src/graph/graph_builder.py
@@ -0,0 +1,4 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+import importlib
+import sys
+sys.modules[__name__] = importlib.import_module("study_supporter.application.use_cases.build_learning_path")
diff --git a/src/graph/schemas.py b/src/graph/schemas.py
new file mode 100644
index 0000000..dd54008
--- /dev/null
+++ b/src/graph/schemas.py
@@ -0,0 +1,6 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+
+import importlib
+import sys
+
+sys.modules[__name__] = importlib.import_module("study_supporter.domain.knowledge_graph")
diff --git a/src/llm/__init__.py b/src/llm/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/src/llm/errors.py b/src/llm/errors.py
new file mode 100644
index 0000000..6833bf4
--- /dev/null
+++ b/src/llm/errors.py
@@ -0,0 +1,6 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+
+import importlib
+import sys
+
+sys.modules[__name__] = importlib.import_module("study_supporter.domain.provider_errors")
diff --git a/src/llm/gemini_client.py b/src/llm/gemini_client.py
new file mode 100644
index 0000000..284cbef
--- /dev/null
+++ b/src/llm/gemini_client.py
@@ -0,0 +1,6 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+
+import importlib
+import sys
+
+sys.modules[__name__] = importlib.import_module("study_supporter.infrastructure.llm.gemini_client")
diff --git a/src/llm/json_utils.py b/src/llm/json_utils.py
new file mode 100644
index 0000000..add1c4e
--- /dev/null
+++ b/src/llm/json_utils.py
@@ -0,0 +1,4 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+import importlib
+import sys
+sys.modules[__name__] = importlib.import_module("study_supporter.infrastructure.llm.json_utils")
diff --git a/src/llm/llm_adapter.py b/src/llm/llm_adapter.py
new file mode 100644
index 0000000..731a39a
--- /dev/null
+++ b/src/llm/llm_adapter.py
@@ -0,0 +1,4 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+import importlib
+import sys
+sys.modules[__name__] = importlib.import_module("study_supporter.application.ports.llm")
diff --git a/src/llm/multi_provider_llm.py b/src/llm/multi_provider_llm.py
new file mode 100644
index 0000000..4eb621c
--- /dev/null
+++ b/src/llm/multi_provider_llm.py
@@ -0,0 +1,8 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+
+import importlib
+import sys
+
+sys.modules[__name__] = importlib.import_module(
+ "study_supporter.infrastructure.llm.multi_provider_llm"
+)
diff --git a/src/llm/ollama_client.py b/src/llm/ollama_client.py
new file mode 100644
index 0000000..66738e5
--- /dev/null
+++ b/src/llm/ollama_client.py
@@ -0,0 +1,4 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+import importlib
+import sys
+sys.modules[__name__] = importlib.import_module("study_supporter.infrastructure.llm.ollama_client")
diff --git a/src/llm/openai_compatible_client.py b/src/llm/openai_compatible_client.py
new file mode 100644
index 0000000..cc04bfd
--- /dev/null
+++ b/src/llm/openai_compatible_client.py
@@ -0,0 +1,8 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+
+import importlib
+import sys
+
+sys.modules[__name__] = importlib.import_module(
+ "study_supporter.infrastructure.llm.openai_compatible_client"
+)
diff --git a/docs/archive/legacy-notes/src/llm/sprint2_notes.md b/src/llm/sprint2_notes.md
similarity index 100%
rename from docs/archive/legacy-notes/src/llm/sprint2_notes.md
rename to src/llm/sprint2_notes.md
diff --git a/src/memory/__init__.py b/src/memory/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/src/memory/long_term.py b/src/memory/long_term.py
new file mode 100644
index 0000000..46e5ac0
--- /dev/null
+++ b/src/memory/long_term.py
@@ -0,0 +1,4 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+import importlib
+import sys
+sys.modules[__name__] = importlib.import_module("study_supporter.infrastructure.persistence.chroma.note_repository")
diff --git a/src/memory/progress_db.py b/src/memory/progress_db.py
new file mode 100644
index 0000000..f511556
--- /dev/null
+++ b/src/memory/progress_db.py
@@ -0,0 +1,8 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+
+import importlib
+import sys
+
+sys.modules[__name__] = importlib.import_module(
+ "study_supporter.infrastructure.persistence.sqlalchemy.progress_repository"
+)
diff --git a/src/memory/short_term.py b/src/memory/short_term.py
new file mode 100644
index 0000000..057c65a
--- /dev/null
+++ b/src/memory/short_term.py
@@ -0,0 +1,4 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+import importlib
+import sys
+sys.modules[__name__] = importlib.import_module("study_supporter.domain.conversation")
diff --git a/docs/archive/legacy-notes/src/memory/sprint4_notes.md b/src/memory/sprint4_notes.md
similarity index 100%
rename from docs/archive/legacy-notes/src/memory/sprint4_notes.md
rename to src/memory/sprint4_notes.md
diff --git a/src/rag/__init__.py b/src/rag/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/src/rag/bm25_index.py b/src/rag/bm25_index.py
new file mode 100644
index 0000000..08ddcfa
--- /dev/null
+++ b/src/rag/bm25_index.py
@@ -0,0 +1,8 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+
+import importlib
+import sys
+
+sys.modules[__name__] = importlib.import_module(
+ "study_supporter.infrastructure.retrieval.bm25_adapter"
+)
diff --git a/src/rag/chunker.py b/src/rag/chunker.py
new file mode 100644
index 0000000..821bb67
--- /dev/null
+++ b/src/rag/chunker.py
@@ -0,0 +1,2 @@
+from study_supporter.ai.ingestion.chunking import * # noqa: F403
+from study_supporter.infrastructure.embeddings.sentences import embed_sentences as embed_sentences
diff --git a/src/rag/embedder.py b/src/rag/embedder.py
new file mode 100644
index 0000000..5fbcadf
--- /dev/null
+++ b/src/rag/embedder.py
@@ -0,0 +1,4 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+import importlib
+import sys
+sys.modules[__name__] = importlib.import_module("study_supporter.infrastructure.embeddings.chunk_embeddings")
diff --git a/src/rag/embedding_provider.py b/src/rag/embedding_provider.py
new file mode 100644
index 0000000..98aef2e
--- /dev/null
+++ b/src/rag/embedding_provider.py
@@ -0,0 +1,8 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+
+import importlib
+import sys
+
+sys.modules[__name__] = importlib.import_module(
+ "study_supporter.infrastructure.embeddings.providers"
+)
diff --git a/src/rag/hybrid_retriever.py b/src/rag/hybrid_retriever.py
new file mode 100644
index 0000000..d1e0ec3
--- /dev/null
+++ b/src/rag/hybrid_retriever.py
@@ -0,0 +1,8 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+
+import importlib
+import sys
+
+sys.modules[__name__] = importlib.import_module(
+ "study_supporter.infrastructure.retrieval.hybrid_adapter"
+)
diff --git a/src/rag/pdf_parser.py b/src/rag/pdf_parser.py
new file mode 100644
index 0000000..1abbc5f
--- /dev/null
+++ b/src/rag/pdf_parser.py
@@ -0,0 +1,8 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+
+import importlib
+import sys
+
+sys.modules[__name__] = importlib.import_module(
+ "study_supporter.infrastructure.documents.pymupdf_parser"
+)
diff --git a/src/rag/schemas.py b/src/rag/schemas.py
new file mode 100644
index 0000000..6e9d09e
--- /dev/null
+++ b/src/rag/schemas.py
@@ -0,0 +1,4 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+import importlib
+import sys
+sys.modules[__name__] = importlib.import_module("study_supporter.domain.documents")
diff --git a/docs/archive/legacy-notes/src/rag/sprint1_notes.md b/src/rag/sprint1_notes.md
similarity index 100%
rename from docs/archive/legacy-notes/src/rag/sprint1_notes.md
rename to src/rag/sprint1_notes.md
diff --git a/docs/archive/legacy-notes/src/rag/sprint1_rag.txt b/src/rag/sprint1_rag.txt
similarity index 100%
rename from docs/archive/legacy-notes/src/rag/sprint1_rag.txt
rename to src/rag/sprint1_rag.txt
diff --git a/src/rag/vector_store.py b/src/rag/vector_store.py
new file mode 100644
index 0000000..b46d844
--- /dev/null
+++ b/src/rag/vector_store.py
@@ -0,0 +1,8 @@
+"""Temporary compatibility alias; canonical implementation is installed."""
+
+import importlib
+import sys
+
+sys.modules[__name__] = importlib.import_module(
+ "study_supporter.infrastructure.persistence.chroma.vector_store"
+)
diff --git a/src/utils/__init__.py b/src/utils/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/src/utils/helpers.py b/src/utils/helpers.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/__init__.py b/tests/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/conftest.py b/tests/conftest.py
new file mode 100644
index 0000000..72b356f
--- /dev/null
+++ b/tests/conftest.py
@@ -0,0 +1,5 @@
+import os
+
+# Before importing legacy services: never connect the offline suite to local/cloud data.
+os.environ["DATABASE_URL"] = "sqlite:///:memory:"
+os.environ.pop("POSTGRES_HOST", None)
diff --git a/tests/eval_rag.py b/tests/eval_rag.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/test_agent.py b/tests/test_agent.py
new file mode 100644
index 0000000..e69de29
diff --git a/backend/tests/unit/test_database_config.py b/tests/test_database_config.py
similarity index 83%
rename from backend/tests/unit/test_database_config.py
rename to tests/test_database_config.py
index ec268be..c13c88b 100644
--- a/backend/tests/unit/test_database_config.py
+++ b/tests/test_database_config.py
@@ -1,6 +1,6 @@
from sqlalchemy.engine import make_url
-from study_supporter.infrastructure.persistence.sqlalchemy.database import _get_database_url
+from src.db.database import _get_database_url
def test_password_with_reserved_characters(monkeypatch):
diff --git a/backend/tests/unit/test_graph.py b/tests/test_graph.py
similarity index 77%
rename from backend/tests/unit/test_graph.py
rename to tests/test_graph.py
index b3114bd..8f7b199 100644
--- a/backend/tests/unit/test_graph.py
+++ b/tests/test_graph.py
@@ -1,14 +1,16 @@
-from study_supporter.ai.graph.algorithms import suggest_learning_path
-from study_supporter.domain.knowledge_graph import ConceptGraph, GraphEdge, GraphNode
-from study_supporter.ai.assessment.json_parsing import parse_llm_model
+import pytest
+
+from src.graph.graph_algorithms import suggest_learning_path
+from src.graph.schemas import ConceptGraph, GraphEdge, GraphNode
+from src.llm.json_utils import parse_llm_model
def test_parse_llm_model_extracts_json_from_surrounding_text():
- response_text = """
+ response_text = '''
Tôi đã trích xuất như sau:
{"nodes": [{"id": "a", "label": "A", "description": "Khái niệm A"}], "edges": []}
Đây là kết quả cuối cùng.
- """
+ '''
graph = parse_llm_model(response_text, ConceptGraph)
diff --git a/backend/tests/unit/test_multi_provider.py b/tests/test_multi_provider.py
similarity index 96%
rename from backend/tests/unit/test_multi_provider.py
rename to tests/test_multi_provider.py
index 44e0de9..3c89664 100644
--- a/backend/tests/unit/test_multi_provider.py
+++ b/tests/test_multi_provider.py
@@ -5,14 +5,11 @@
import time
import pytest
-from unittest.mock import MagicMock
-
-from study_supporter.application.ports.llm import ChatResponse
-from study_supporter.infrastructure.llm.multi_provider_llm import MultiProviderLLM
-from study_supporter.infrastructure.llm.openai_compatible_client import (
- QuotaExhaustedError,
- RateLimitError,
-)
+from unittest.mock import MagicMock, patch
+
+from src.llm.llm_adapter import ChatResponse
+from src.llm.multi_provider_llm import MultiProviderLLM
+from src.llm.openai_compatible_client import QuotaExhaustedError, RateLimitError
def _make_mock_provider(name: str, response_text: str = "OK") -> MagicMock:
diff --git a/backend/tests/unit/test_quiz.py b/tests/test_quiz.py
similarity index 81%
rename from backend/tests/unit/test_quiz.py
rename to tests/test_quiz.py
index 896d844..2b91d59 100644
--- a/backend/tests/unit/test_quiz.py
+++ b/tests/test_quiz.py
@@ -1,10 +1,8 @@
-from study_supporter.ai.assessment.legacy_parser import (
- parse_quiz_from_text as _parse_quiz_from_text,
-)
+from ui.components.quiz_arena import _parse_quiz_from_text
def test_parse_multi_question_quiz_text():
- text = """
+ text = '''
Câu 1: What is 2+2?
A. 3
B. 4 (Đáp án đúng)
@@ -18,7 +16,7 @@ def test_parse_multi_question_quiz_text():
C. Paris (Đáp án đúng)
D. Madrid
Giải thích: Paris is the capital of France.
-"""
+'''
questions = _parse_quiz_from_text(text)
diff --git a/backend/tests/unit/test_quiz_content_source.py b/tests/test_quiz_content_source.py
similarity index 86%
rename from backend/tests/unit/test_quiz_content_source.py
rename to tests/test_quiz_content_source.py
index bcfe486..f17f61a 100644
--- a/backend/tests/unit/test_quiz_content_source.py
+++ b/tests/test_quiz_content_source.py
@@ -1,4 +1,4 @@
-from study_supporter.orchestration.legacy_react.tools.generate_quiz import GenerateQuizTool
+from src.agent.tools.generate_quiz import GenerateQuizTool
class DummyLLM:
diff --git a/backend/tests/unit/test_react_baseline.py b/tests/test_react_baseline.py
similarity index 89%
rename from backend/tests/unit/test_react_baseline.py
rename to tests/test_react_baseline.py
index 833ff29..5bcf993 100644
--- a/backend/tests/unit/test_react_baseline.py
+++ b/tests/test_react_baseline.py
@@ -1,7 +1,7 @@
from unittest.mock import Mock
-from study_supporter.orchestration.legacy_react.orchestrator import ReActOrchestrator
-from study_supporter.application.ports.llm import ChatResponse
+from src.agent.orchestrator import ReActOrchestrator
+from src.llm.llm_adapter import ChatResponse
def test_react_executes_mock_tool_then_returns_final_answer():
diff --git a/ui/__init__.py b/ui/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/ui/application_bridge.py b/ui/application_bridge.py
new file mode 100644
index 0000000..f56ee59
--- /dev/null
+++ b/ui/application_bridge.py
@@ -0,0 +1,3 @@
+import importlib
+import sys
+sys.modules[__name__] = importlib.import_module("apps.streamlit_legacy.application_bridge")
diff --git a/ui/components/auth.py b/ui/components/auth.py
new file mode 100644
index 0000000..39bb91d
--- /dev/null
+++ b/ui/components/auth.py
@@ -0,0 +1,4 @@
+import importlib
+import sys
+
+sys.modules[__name__] = importlib.import_module("apps.streamlit_legacy.components.auth")
diff --git a/ui/components/chat.py b/ui/components/chat.py
new file mode 100644
index 0000000..7adc4a6
--- /dev/null
+++ b/ui/components/chat.py
@@ -0,0 +1,4 @@
+import importlib
+import sys
+
+sys.modules[__name__] = importlib.import_module("apps.streamlit_legacy.components.chat")
diff --git a/ui/components/graph_viewer.py b/ui/components/graph_viewer.py
new file mode 100644
index 0000000..8f2c46b
--- /dev/null
+++ b/ui/components/graph_viewer.py
@@ -0,0 +1,3 @@
+import importlib
+import sys
+sys.modules[__name__] = importlib.import_module("apps.streamlit_legacy.components.graph_viewer")
diff --git a/ui/components/quiz_arena.py b/ui/components/quiz_arena.py
new file mode 100644
index 0000000..e9bb9c9
--- /dev/null
+++ b/ui/components/quiz_arena.py
@@ -0,0 +1,6 @@
+from apps.streamlit_legacy.components.quiz_arena import render_quiz_arena as render_quiz_arena
+from study_supporter.ai.assessment.legacy_parser import (
+ parse_quiz_from_text as _parse_quiz_from_text,
+)
+
+__all__ = ["render_quiz_arena", "_parse_quiz_from_text"]
diff --git a/ui/components/sidebar.py b/ui/components/sidebar.py
new file mode 100644
index 0000000..fa0aad5
--- /dev/null
+++ b/ui/components/sidebar.py
@@ -0,0 +1,4 @@
+import importlib
+import sys
+
+sys.modules[__name__] = importlib.import_module("apps.streamlit_legacy.components.sidebar")
diff --git a/ui/dashboard.py b/ui/dashboard.py
new file mode 100644
index 0000000..9fd9f71
--- /dev/null
+++ b/ui/dashboard.py
@@ -0,0 +1,27 @@
+import streamlit as st
+
+def render_chat():
+ if st.session_state.orchestrator is None:
+ st.info("👈 Hãy upload tài liệu ở sidebar bên trái trước.")
+ return
+
+ for msg in st.session_state.chat_history:
+ with st.chat_message(msg["role"]):
+ st.markdown(msg["content"])
+
+ user_question = st.chat_input("Hỏi gì đó về tài liệu...")
+
+ if user_question:
+ st.session_state.chat_history.append({"role": "user", "content": user_question})
+ with st.chat_message("user"):
+ st.markdown(user_question)
+
+ with st.chat_message("assistant"):
+ with st.spinner("Đang suy nghĩ..."):
+ state = st.session_state.orchestrator.run(user_question)
+
+ st.markdown(state.final_answer)
+ st.session_state.last_scratchpad = state.render_scratchpad() # để Thought Log sidebar đọc
+
+ st.session_state.chat_history.append({"role": "assistant", "content": state.final_answer})
+ st.rerun() # rerun để Thought Log ở sidebar cập nhật ngay
\ No newline at end of file
diff --git a/ui/router.py b/ui/router.py
new file mode 100644
index 0000000..21627a5
--- /dev/null
+++ b/ui/router.py
@@ -0,0 +1,3 @@
+import importlib
+import sys
+sys.modules[__name__] = importlib.import_module("apps.streamlit_legacy.router")