readloops 2.3.0__tar.gz → 2.6.3__tar.gz

{readloops-2.3.0 → readloops-2.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: readloops
-Version: 2.3.0
+Version: 2.6.3
 Summary: AI 驱动的英语阅读训练器：可理解输入 + FSRS 间隔重复
 Author: Fangyuan2711
 License: MIT
@@ -38,9 +38,22 @@ Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
 Requires-Dist: pre-commit>=3.7; extra == "dev"
 Dynamic: license-file
 
-# ReadLoops
+<p align="center">
+  <img src="https://raw.githubusercontent.com/pekoqq/ReadLoops/main/assets/logo.png" width="104" alt="ReadLoops logo">
+</p>
 
-> AI 驱动的英语阅读训练器。基于「可理解输入（i+1）」+ 阅读驱动的 FSRS 间隔重复，面向大学英语四级（进阶六级）。
+<h1 align="center">ReadLoops</h1>
+
+<p align="center">
+  <a href="https://pypi.org/project/readloops/"><img alt="PyPI" src="https://img.shields.io/pypi/v/readloops"></a>
+  <a href="https://pypi.org/project/readloops/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/readloops"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green"></a>
+  <a href="https://github.com/pekoqq/ReadLoops/releases"><img alt="Release" src="https://img.shields.io/github/v/release/pekoqq/ReadLoops"></a>
+</p>
+
+<p align="center">
+  AI 驱动的英语阅读训练器。基于「可理解输入（i+1）」+ 阅读驱动的 FSRS 间隔重复，面向大学英语四级（进阶六级）。
+</p>
 
 ## 它解决什么问题
 

{readloops-2.3.0 → readloops-2.6.3}/README.md

@@ -1,6 +1,19 @@
-# ReadLoops
-
-> AI 驱动的英语阅读训练器。基于「可理解输入（i+1）」+ 阅读驱动的 FSRS 间隔重复，面向大学英语四级（进阶六级）。
+<p align="center">
+  <img src="https://raw.githubusercontent.com/pekoqq/ReadLoops/main/assets/logo.png" width="104" alt="ReadLoops logo">
+</p>
+
+<h1 align="center">ReadLoops</h1>
+
+<p align="center">
+  <a href="https://pypi.org/project/readloops/"><img alt="PyPI" src="https://img.shields.io/pypi/v/readloops"></a>
+  <a href="https://pypi.org/project/readloops/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/readloops"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green"></a>
+  <a href="https://github.com/pekoqq/ReadLoops/releases"><img alt="Release" src="https://img.shields.io/github/v/release/pekoqq/ReadLoops"></a>
+</p>
+
+<p align="center">
+  AI 驱动的英语阅读训练器。基于「可理解输入（i+1）」+ 阅读驱动的 FSRS 间隔重复，面向大学英语四级（进阶六级）。
+</p>
 
 ## 它解决什么问题
 

{readloops-2.3.0 → readloops-2.6.3}/app/api/articles.py

@@ -4,6 +4,7 @@ import json
 from fastapi import APIRouter, HTTPException
 
 from app.database import get_db
+from app.services import encounter, mastery
 from app.services.ai import generate_article
 
 router = APIRouter(prefix="/api/articles", tags=["articles"])
@@ -15,6 +16,15 @@ async def generate():
     article = generate_article()
     if not article:
         raise HTTPException(status_code=500, detail="无法生成文章，请检查 AI 配置")
+    targets = json.loads(article.target_words) if article.target_words else []
+    # 生成即记「遇见」：方法的要害是「在变化语境中反复遇见」，而系统此前只在
+    # 用户查词时才计数 —— 看到了但没查就完全不算，重遇统计永远起不来。
+    try:
+        encounter.record_article(article.id, article.content, targets)
+        # 遇见改变了识别层的证据，立刻重算（只算这一篇涉及到的词）
+        mastery.refresh()
+    except Exception:
+        pass  # 记录失败不能影响文章生成
     return {
         "id": article.id,
         "title": article.title,
@@ -22,7 +32,9 @@ async def generate():
         "source": article.source,
         "word_count": article.word_count,
         "new_word_count": article.new_word_count,
-        "target_words": json.loads(article.target_words) if article.target_words else [],
+        "target_words": targets,
+        # 短语单列出来，前端可以分开展示「本篇补的单词 / 短语」
+        "target_phrases": [t for t in targets if " " in t],
         "created_at": article.created_at,
     }
 
@@ -93,5 +105,10 @@ async def delete_article(article_id: int):
         # 先删除关联数据，再删除文章本身（避免外键约束失败）
         conn.execute("DELETE FROM highlights WHERE article_id = ?", (article_id,))
         conn.execute("DELETE FROM reading_sessions WHERE article_id = ?", (article_id,))
+        # ⚠️ 遇见记录也必须一起清。
+        # 重遇次数按 COUNT(DISTINCT article_id) 计算，而统计口径包含 action='lookup' ——
+        # 文章删了、记录还在，就成了「幽灵文章」：明明只剩 5 篇，界面却显示跨 6 篇。
+        # 实测就这么虚高过（journal 多算 1 篇）。
+        conn.execute("DELETE FROM word_encounters WHERE article_id = ?", (article_id,))
         conn.execute("DELETE FROM articles WHERE id = ?", (article_id,))
-    return {"status": "ok", "message": "文章已删除"}
+    return {"status": "ok", "message": "文章已删除（含它产生的遇见记录）"}

readloops-2.6.3/app/api/books.py

@@ -0,0 +1,59 @@
+"""书架 API：公共领域书籍的搜索、下载、导入材料。
+
+只接 Project Gutenberg。这类书籍版权已过期，可合法下载与再加工，
+是唯一没有版权风险的语料来源。
+"""
+from fastapi import APIRouter, HTTPException
+
+from app.services import bookshelf as bs
+from app.services import materials as mt
+
+router = APIRouter(prefix="/api/books", tags=["books"])
+
+
+@router.get("/search")
+def search(q: str = "", page: int = 1, language: str = "en"):
+    if not q.strip():
+        return {"results": [], "page": page, "has_next": False}
+    try:
+        return bs.search_books(q, page=page, language=language)
+    except Exception as e:
+        raise HTTPException(status_code=502, detail=f"书源访问失败：{e}")
+
+
+@router.get("")
+def list_all(status: str | None = None):
+    return bs.list_books(status=status)
+
+
+@router.post("/download")
+def download(payload: dict):
+    source_id = str(payload.get("source_id") or "").strip()
+    if not source_id:
+        raise HTTPException(status_code=400, detail="缺少 source_id")
+    result = bs.download_book(
+        source_id,
+        title=payload.get("title", ""),
+        author=payload.get("author", ""),
+        language=payload.get("language", "en"),
+        subjects=payload.get("subjects") or [],
+    )
+    if not result.get("ok"):
+        raise HTTPException(status_code=502, detail=result.get("error", "下载失败"))
+    return result
+
+
+@router.post("/{book_id}/import")
+def import_as_material(book_id: int):
+    """把书架里的书导入为材料，供蒸馏与出题使用。"""
+    result = mt.import_book(book_id)
+    if not result.get("ok"):
+        raise HTTPException(status_code=400, detail=result.get("error", "导入失败"))
+    return result
+
+
+@router.delete("/{book_id}")
+def remove(book_id: int):
+    if not bs.delete_book(book_id):
+        raise HTTPException(status_code=404, detail="书籍不存在")
+    return {"ok": True}

readloops-2.6.3/app/api/graph.py

@@ -0,0 +1,46 @@
+"""知识图谱 API。
+
+同一份图两套用途：前端力导向可视化（给用户看）+ 邻接检索（给 AI 用）。
+"""
+from fastapi import APIRouter, HTTPException
+
+from app.services import graph as g
+
+router = APIRouter(prefix="/api/graph", tags=["graph"])
+
+
+@router.get("")
+def get_graph(types: str = "", limit: int = 400):
+    """取图数据。types 用逗号分隔，例如 word,phrase。"""
+    node_types = [t.strip() for t in types.split(",") if t.strip()] or None
+    return g.get_graph(node_types=node_types, limit=max(20, min(limit, 1200)))
+
+
+@router.get("/stats")
+def stats():
+    return g.stats()
+
+
+@router.get("/node/{node_id}")
+def neighbors(node_id: int, depth: int = 1):
+    return g.neighbors(node_id, depth=max(1, min(depth, 3)))
+
+
+@router.post("/rebuild")
+def rebuild(payload: dict | None = None):
+    payload = payload or {}
+    try:
+        return g.rebuild(
+            include_words=bool(payload.get("words", True)),
+            include_phrases=bool(payload.get("phrases", True)),
+            include_docs=bool(payload.get("docs", True)),
+            max_nodes=int(payload.get("max_nodes", 600)),
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"重建失败：{e}")
+
+
+@router.delete("")
+def clear():
+    g.clear()
+    return {"ok": True}

readloops-2.6.3/app/api/materials.py

@@ -0,0 +1,88 @@
+"""材料与蒸馏 API。
+
+材料 = 用户自己的文本（粘贴 / 文件 / 书架导入）。
+蒸馏 = 从材料里提取统计特征，产出「风格画像」，供文章生成参考。
+画像里只有统计量，不含原文。
+"""
+from fastapi import APIRouter, HTTPException
+
+from app.services import distill as ds
+from app.services import materials as mt
+
+router = APIRouter(prefix="/api/materials", tags=["materials"])
+
+
+@router.get("")
+def list_all():
+    return mt.list_materials()
+
+
+@router.post("/paste")
+def paste(payload: dict):
+    result = mt.import_text(payload.get("title", ""), payload.get("content", ""))
+    if not result.get("ok"):
+        raise HTTPException(status_code=400, detail=result.get("error", "导入失败"))
+    return result
+
+
+@router.post("/import")
+def import_path(payload: dict):
+    path = payload.get("path", "")
+    if not path:
+        raise HTTPException(status_code=400, detail="缺少文件路径")
+    result = mt.import_file(path, title=payload.get("title"))
+    if not result.get("ok"):
+        # 解析失败也返回 200 + ok:false，前端要展示具体原因（例如缺 PDF 依赖）
+        return result
+    return result
+
+
+@router.get("/{material_id}")
+def detail(material_id: int, with_content: bool = False):
+    m = mt.get_material(material_id, with_content=with_content)
+    if not m:
+        raise HTTPException(status_code=404, detail="材料不存在")
+    return m
+
+
+@router.delete("/{material_id}")
+def remove(material_id: int):
+    if not mt.delete_material(material_id):
+        raise HTTPException(status_code=404, detail="材料不存在")
+    return {"ok": True}
+
+
+# ---------------------------------------------------------------- 蒸馏
+
+@router.post("/distill")
+def distill(payload: dict):
+    ids = payload.get("material_ids") or []
+    if not isinstance(ids, list) or not ids:
+        raise HTTPException(status_code=400, detail="请选择至少一份材料")
+    result = ds.distill_materials(
+        [int(i) for i in ids],
+        name=payload.get("name", ""),
+        activate=bool(payload.get("activate", False)),
+    )
+    if not result.get("ok"):
+        raise HTTPException(status_code=400, detail=result.get("error", "蒸馏失败"))
+    return result
+
+
+@router.get("/profiles/all")
+def profiles():
+    return ds.list_profiles()
+
+
+@router.post("/profiles/{profile_id}/activate")
+def activate(profile_id: int):
+    if not ds.activate_profile(profile_id):
+        raise HTTPException(status_code=404, detail="画像不存在")
+    return {"ok": True}
+
+
+@router.delete("/profiles/{profile_id}")
+def remove_profile(profile_id: int):
+    if not ds.delete_profile(profile_id):
+        raise HTTPException(status_code=404, detail="画像不存在")
+    return {"ok": True}

readloops-2.6.3/app/api/placement.py

@@ -0,0 +1,38 @@
+"""词汇量定级测试 API。
+
+无状态设计：GET 出题 → 客户端本地作答 → POST 一次性提交评分。
+服务器不保存进行中的试卷，省掉一整类「会话过期 / 并发覆盖」问题。
+"""
+from fastapi import APIRouter, HTTPException
+
+from app.services import placement as pl
+
+router = APIRouter(prefix="/api/placement", tags=["placement"])
+
+
+@router.get("/items")
+def items(per_band: int = pl.ITEMS_PER_BAND, pseudo: int = pl.PSEUDO_COUNT):
+    """生成一份测试卷。"""
+    return pl.build_items(
+        items_per_band=max(3, min(per_band, 60)),
+        pseudo_count=max(0, min(pseudo, len(pl.PSEUDO_WORDS))),
+    )
+
+
+@router.post("/submit")
+def submit(payload: dict):
+    """提交作答，评分并落库。payload: {"answers": [{"text": "...", "known": true}]}"""
+    answers = payload.get("answers")
+    if not isinstance(answers, list) or not answers:
+        raise HTTPException(status_code=400, detail="没有作答内容")
+    result = pl.score(answers)
+    if not result["bands"]:
+        raise HTTPException(status_code=400, detail="作答内容无法匹配到题库，请重新测试")
+    result["run_id"] = pl.save_run(result, answers)
+    return result
+
+
+@router.get("/summary")
+def summary():
+    """最近一次测试结果（没测过返回 has_result: false）。"""
+    return pl.summary()

{readloops-2.3.0 → readloops-2.6.3}/app/api/reading.py

@@ -45,6 +45,9 @@ async def record_lookup(word_id: int = 0, article_id: int = 0, context: str = ""
                 "VALUES (?, ?, ?, 'lookup', ?)",
                 (word_id, article_id or None, context, now),
             )
+            # 查词是掌握度模型里权重很高的负向证据，立刻重算该词
+            from app.services import mastery
+            mastery.refresh([word_id])
             # 获取当前 lookup_count（更新前）
             row = conn.execute("SELECT lookup_count, status FROM words WHERE id=?", (word_id,)).fetchone()
             if row:

{readloops-2.3.0 → readloops-2.6.3}/app/api/stats.py

@@ -2,10 +2,11 @@
 import time
 
 import httpx
-from fastapi import APIRouter
+from fastapi import APIRouter, HTTPException
 from pydantic import BaseModel
 
 from app.database import get_db
+from app.services import encounter, mastery, selection, vocab_gap
 
 router = APIRouter(prefix="/api", tags=["stats"])
 
@@ -96,6 +97,7 @@ async def stats_overview():
         "vocab_estimate": vocab_estimate,
         "test_accuracy": round(test_correct / test_total * 100, 1) if test_total > 0 else 0,
         "srs": srs,
+        "reentry": encounter.summary(),
         "hot_words": [{"text": r["text"], "count": r["lookup_count"]} for r in hot_words],
     }
 
@@ -252,3 +254,55 @@ async def test_api_connection(req: TestApiRequest):
             return {"ok": False, "error": f"HTTP {resp2.status_code}: {resp2.text[:100]}"}
     except Exception as e:
         return {"ok": False, "error": str(e)[:100]}
+
+
+@router.get("/stats/reentry")
+def reentry(limit: int = 200, only_active: bool = True):
+    """重遇进度：每个学习词跨了多少篇文章。
+
+    口径是「跨多少篇」而不是「见了几次」—— 方法要求的是**变化的语境**，
+    同一篇文章里看 12 遍没有意义。
+    """
+    return {
+        "summary": encounter.summary(),
+        "items": encounter.reentry_stats(limit=max(1, min(limit, 1000)),
+                                         only_active=only_active),
+    }
+
+
+@router.get("/stats/vocab-gap")
+def vocab_gap_overview():
+    """词汇差距：词汇量、真题覆盖率、各考试缺口、进度预测。
+
+    覆盖率不是「认识多少词表里的词」，而是**按词频档位给语料加权** ——
+    实测 CET4 大纲词表只覆盖四级真题语料 15.8% 的 token（词表装的是内容词，
+    剩下 84% 是基础词与功能词），拿词表百分比当「能读懂多少」会严重失真。
+    """
+    # 没有定级结果时铺一条默认假设，否则新用户的整页数字都是空的
+    from app.services import placement as pl
+    pl.ensure_default_run()
+    return vocab_gap.overview()
+
+
+@router.get("/stats/target-exam")
+def get_target_exam():
+    """当前目标考试。"""
+    return {"exam": selection.target_exam(),
+            "label": selection.EXAM_LABELS.get(selection.target_exam(), ""),
+            "options": [{"key": k, "label": v} for k, v in selection.EXAM_LABELS.items()]}
+
+
+@router.post("/stats/target-exam")
+def set_target_exam(payload: dict):
+    """设置目标考试 —— 它决定下一篇埋哪些词。"""
+    exam = str(payload.get("exam", "")).strip()
+    if not selection.set_target_exam(exam):
+        raise HTTPException(status_code=400, detail=f"不支持的考试：{exam}")
+    return {"ok": True, "exam": exam,
+            "label": selection.EXAM_LABELS.get(exam, "")}
+
+
+@router.get("/stats/mastery")
+def mastery_stats():
+    """掌握度分布：识别 vs 回忆分开统计。"""
+    return mastery.stats()