Project-N-E-K-O
diff --git a/‎plugin/plugins/study_companion/__init__.py‎
Lines changed: 159 additions & 11 deletions b/‎plugin/plugins/study_companion/__init__.py‎
Lines changed: 159 additions & 11 deletions
@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+from pathlib import Path
 import threading
 import time
 from typing import Any
@@ -37,6 +38,8 @@
     build_tutor_payload,
 )
 from .mode_manager import ModeManager, build_transition_phrase, handle_user_intent, normalize_mode
+from .knowledge_contribution import PublicGraphContributionBuilder
+from .knowledge_tracker import KnowledgeTracker
 from .state import build_initial_state
 from .store import StudyStore
 from .study_ocr_pipeline import StudyOcrPipeline
@@ -52,18 +55,24 @@ def __init__(self, ctx):
         self.file_logger = self.enable_file_logging(log_level="INFO")
         self.logger = self.file_logger
         self._lock = threading.RLock()
-        self._install_lock = threading.Lock()
-        self._rapidocr_models_lock = threading.Lock()
+        self._install_in_progress = False
+        self._rapidocr_models_in_progress = False
         self._cfg = StudyConfig()
         self._state = build_initial_state(mode=MODE_COMPANION)
         self._store = StudyStore(
             self.data_path("study_companion.db"),
             self.config_dir / "data" / "study_seed.json",
             self.logger,
+            Path(__file__).resolve().parent / "static" / "knowledge_graph_seed.json",
         )
         self._ocr_pipeline: StudyOcrPipeline | None = None
         self._agent: TutorLLMAgent | None = None
         self._mode_manager = ModeManager()
+        self._knowledge_tracker = KnowledgeTracker(
+            self._store,
+            retention_target=self._cfg.fsrs_retention_target,
+            logger=self.logger,
+        )
 
     @lifecycle(id="startup")
     async def startup(self, **_):
@@ -72,6 +81,11 @@ async def startup(self, **_):
             self._cfg = build_config(raw if isinstance(raw, dict) else {})
             await asyncio.to_thread(self._store.open)
             self._cfg = await asyncio.to_thread(self._store.load_config, self._cfg)
+            self._knowledge_tracker = KnowledgeTracker(
+                self._store,
+                retention_target=self._cfg.fsrs_retention_target,
+                logger=self.logger,
+            )
             restored = await asyncio.to_thread(self._store.load_state, build_initial_state(mode=self._cfg.mode))
             with self._lock:
                 self._state = restored
@@ -201,7 +215,15 @@ async def _apply_mode_switch(self, mode: str, reason: str, *, language: str | No
 
     def _status_payload(self) -> dict[str, Any]:
         history = self._store.list_interactions(limit=10)
-        return build_status_payload(config=self._cfg, state=self._state, history=history)
+        knowledge = {
+            "knowledge_summary": self._knowledge_tracker.get_status_summary(limit=8),
+            "knowledge_quality_summary": self._knowledge_tracker.quality.status_summary(limit=8),
+            "anonymous_knowledge_stats_summary": self._store.anonymous_knowledge_stats_summary(),
+            "review_queue": self._knowledge_tracker.get_review_queue(limit=8),
+            "weak_topics": self._knowledge_tracker.get_weak_topics(limit=8),
+            "mastery_overview": self._store.list_mastery_overview(limit=8),
+        }
+        return build_status_payload(config=self._cfg, state=self._state, history=history, knowledge=knowledge)
 
     def _state_snapshot(self) -> dict[str, Any]:
         with self._lock:
@@ -299,6 +321,23 @@ async def _build_learning_context(
             "last_ocr_at": snapshot.get("last_ocr_at") or "",
             "history": history,
         }
+        if operation == LLM_OPERATION_QUESTION_GENERATE:
+            hint = ""
+            if extra:
+                hint = str(extra.get("topic_hint") or extra.get("topic") or "").strip()
+            context["knowledge_question_params"] = await asyncio.to_thread(
+                self._knowledge_tracker.get_next_question_params,
+                hint,
+            )
+        elif operation == LLM_OPERATION_SUMMARIZE_SESSION:
+            context["knowledge_session_summary"] = await asyncio.to_thread(
+                self._knowledge_tracker.get_session_summary
+            )
+        else:
+            context["knowledge_summary"] = await asyncio.to_thread(
+                self._knowledge_tracker.get_status_summary,
+                limit=5,
+            )
         if extra:
             context.update(extra)
         return context
@@ -404,6 +443,56 @@ async def _track_learning(
                 created_at=utc_now_iso(),
             )
         self._record_tutor_result(LLM_OPERATION_KNOWLEDGE_TRACK, track_reply)
+        if operation == LLM_OPERATION_ANSWER_EVALUATE:
+            await self._record_answer_knowledge(reply, track_reply, extra_context=extra_context)
+
+    async def _record_answer_knowledge(
+        self,
+        eval_reply: TutorReply,
+        track_reply: TutorReply,
+        *,
+        extra_context: dict[str, Any] | None = None,
+    ) -> None:
+        context = dict(extra_context or {})
+        track_payload = dict(track_reply.payload or {})
+        eval_payload = dict(eval_reply.payload or {})
+        current_question = dict(context.get("current_question") or {})
+        question_payload = dict(context.get("question_payload") or current_question)
+        question_text = str(context.get("question") or question_payload.get("question") or current_question.get("question") or "").strip()
+        question_payload["question"] = question_text
+        question_payload["answer"] = str(context.get("expected_answer") or question_payload.get("answer") or current_question.get("answer") or "")
+        topic = str(
+            question_payload.get("topic")
+            or track_payload.get("topic")
+            or eval_payload.get("topic")
+            or self._guess_track_topic(track_reply)
+        ).strip()
+        if topic:
+            question_payload.setdefault("topic", topic)
+        eval_result = {
+            **eval_payload,
+            "topic": topic,
+            "track": track_payload,
+        }
+        session_id = str(
+            context.get("session_id")
+            or context.get("run_id")
+            or getattr(self._state, "run_id", "")
+            or getattr(self.ctx, "run_id", "")
+            or "default"
+        ).strip() or "default"
+        try:
+            await asyncio.to_thread(
+                self._knowledge_tracker.on_answer,
+                topic_id=topic,
+                question=question_payload,
+                user_answer=str(context.get("answer") or eval_reply.input_text or ""),
+                eval_result=eval_result,
+                mode=str(context.get("mode") or self._state.active_mode),
+                session_id=session_id,
+            )
+        except Exception as exc:
+            self.logger.warning("study knowledge tracker persistence failed: {}", exc)
 
     @staticmethod
     def _guess_track_topic(reply: TutorReply) -> str:
@@ -416,6 +505,10 @@ def _guess_track_topic(reply: TutorReply) -> str:
         return first_line[:48] or "general"
 
     def _resolve_current_run_id(self, extra_args: dict[str, Any] | None = None) -> str:
+        if isinstance(extra_args, dict):
+            direct = str(extra_args.get("run_id") or "").strip()
+            if direct:
+                return direct
         current = str(getattr(self.ctx, "run_id", "") or "").strip()
         if current:
             return current
@@ -470,6 +563,41 @@ async def study_status(self, **_):
         payload = await asyncio.to_thread(self._status_payload)
         return Ok(payload)
 
+    @plugin_entry(
+        id="study_knowledge_quality_status",
+        name=tr("entries.knowledge_quality_status.name", default="Study Knowledge Quality Status"),
+        description=tr("entries.knowledge_quality_status.description", default="Return candidate knowledge quality counts and recent evidence."),
+        input_schema={"type": "object", "properties": {"limit": {"type": "integer", "default": 20}}},
+        llm_result_fields=["total", "by_status", "recent_evidence"],
+    )
+    async def study_knowledge_quality_status(self, limit: int = 20, **_):
+        payload = await asyncio.to_thread(self._knowledge_tracker.quality.status_summary, limit=max(1, int(limit or 20)))
+        return Ok(payload)
+
+    @plugin_entry(
+        id="study_anonymous_knowledge_preview",
+        name=tr("entries.anonymous_knowledge_preview.name", default="Study Anonymous Knowledge Preview"),
+        description=tr("entries.anonymous_knowledge_preview.description", default="Build and return a local anonymized knowledge contribution preview. Phase 4 does not upload it."),
+        input_schema={"type": "object", "properties": {"limit": {"type": "integer", "default": 100}}},
+        llm_result_fields=["summary", "stats", "opt_in"],
+    )
+    async def study_anonymous_knowledge_preview(self, limit: int = 100, **_):
+        builder = PublicGraphContributionBuilder(self._store, self._cfg)
+        payload = await asyncio.to_thread(builder.preview, limit=max(1, int(limit or 100)))
+        return Ok(payload)
+
+    @plugin_entry(
+        id="study_clear_knowledge_contribution_queue",
+        name=tr("entries.clear_knowledge_contribution_queue.name", default="Clear Study Knowledge Contribution Queue"),
+        description=tr("entries.clear_knowledge_contribution_queue.description", default="Clear the local anonymous knowledge contribution queue."),
+        input_schema={"type": "object", "properties": {}},
+        llm_result_fields=["cleared_count"],
+    )
+    async def study_clear_knowledge_contribution_queue(self, **_):
+        builder = PublicGraphContributionBuilder(self._store, self._cfg)
+        cleared = await asyncio.to_thread(builder.clear_queue)
+        return Ok({"cleared_count": cleared})
+
     @plugin_entry(
         id="study_detect_mode_intent",
         name=tr("entries.detect_mode_intent.name", default="Detect Study Mode Intent"),
@@ -690,7 +818,7 @@ async def study_generate_question(self, text: str = "", topic: str = "", **_):
         timeout=60.0,
         llm_result_fields=["summary", "verdict", "score", "error_type", "feedback", "next_action"],
     )
-    async def study_evaluate_answer(self, answer: str = "", question: str = "", expected_answer: str = "", **_):
+    async def study_evaluate_answer(self, answer: str = "", question: str = "", expected_answer: str = "", **kwargs):
         if self._agent is None:
             return Err(SdkError("study tutor agent is not initialized"))
         with self._lock:
@@ -707,14 +835,28 @@ async def study_evaluate_answer(self, answer: str = "", question: str = "", expe
         if not resolved_expected and (not supplied_question or supplied_question == state_question):
             resolved_expected = state_expected
         answer_text = str(answer or "").strip()
+        using_current_question = not supplied_question or supplied_question == state_question
+        question_payload = dict(current_question) if using_current_question else {}
+        question_payload.update(
+            {
+                "question": resolved_question,
+                "answer": resolved_expected,
+            }
+        )
+        run_id = self._resolve_current_run_id(kwargs)
+        session_id = str(kwargs.get("session_id") or "").strip()
         tutor_context = await self._build_learning_context(
             LLM_OPERATION_ANSWER_EVALUATE,
             input_text=answer_text,
             extra={
                 "question": resolved_question,
                 "expected_answer": resolved_expected,
                 "answer": answer_text,
-                "current_question": current_question,
+                "current_question": current_question if using_current_question else {},
+                "question_payload": question_payload,
+                "question_source": "current_question" if using_current_question else "supplied",
+                "run_id": run_id,
+                "session_id": session_id,
                 "mode": active_mode,
             },
         )
@@ -790,8 +932,10 @@ async def study_summarize_session(self, focus: str = "", **_):
         llm_result_fields=["summary"],
     )
     async def study_install_tesseract(self, force: bool = False, **kwargs):
-        if not self._install_lock.acquire(blocking=False):
-            return Err(SdkError("Tesseract install is already running"))
+        with self._lock:
+            if self._install_in_progress:
+                return Err(SdkError("Tesseract install is already running"))
+            self._install_in_progress = True
         run_id = self._resolve_current_run_id(kwargs)
         try:
             from plugin.plugins.galgame_plugin.tesseract_support import install_tesseract
@@ -814,7 +958,8 @@ async def study_install_tesseract(self, force: bool = False, **kwargs):
         except Exception as exc:
             return Err(SdkError(f"Tesseract install failed: {exc}"))
         finally:
-            self._install_lock.release()
+            with self._lock:
+                self._install_in_progress = False
 
     @plugin_entry(
         id="study_download_rapidocr_models",
@@ -825,8 +970,10 @@ async def study_install_tesseract(self, force: bool = False, **kwargs):
         llm_result_fields=["summary"],
     )
     async def study_download_rapidocr_models(self, force: bool = False, **kwargs):
-        if not self._rapidocr_models_lock.acquire(blocking=False):
-            return Err(SdkError("RapidOCR model download is already running"))
+        with self._lock:
+            if self._rapidocr_models_in_progress:
+                return Err(SdkError("RapidOCR model download is already running"))
+            self._rapidocr_models_in_progress = True
         run_id = self._resolve_current_run_id(kwargs)
         try:
             from plugin.plugins.galgame_plugin.rapidocr_support import download_rapidocr_models
@@ -859,7 +1006,8 @@ async def study_download_rapidocr_models(self, force: bool = False, **kwargs):
         except Exception as exc:
             return Err(SdkError(f"RapidOCR model download failed: {exc}"))
         finally:
-            self._rapidocr_models_lock.release()
+            with self._lock:
+                self._rapidocr_models_in_progress = False
 
 
 StudyCompanionBridgePlugin = StudyCompanionPlugin