examforge 0.2.0.post9__tar.gz

examforge-0.2.0.post9/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: examforge
+Version: 0.2.0.post9
+Summary: CLI-first multimodal exam-preparation engine with a canonical learning IR
+Requires-Python: >=3.12
+Requires-Dist: pydantic<3,>=2.8
+Provides-Extra: document
+Requires-Dist: pymupdf>=1.24; extra == "document"
+Requires-Dist: pymupdf4llm>=0.0.17; extra == "document"
+Requires-Dist: python-docx>=1.1; extra == "document"
+Requires-Dist: pytesseract>=0.3.13; extra == "document"
+Requires-Dist: opencv-python>=4.10; extra == "document"
+Provides-Extra: knowledge
+Requires-Dist: neo4j>=5.25; extra == "knowledge"
+Requires-Dist: qdrant-client>=1.12; extra == "knowledge"
+Provides-Extra: generation
+Requires-Dist: manim>=0.18; extra == "generation"
+Provides-Extra: audio
+Requires-Dist: openai-whisper>=20240930; extra == "audio"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.13; extra == "dev"

examforge-0.2.0.post9/README.md

@@ -0,0 +1,79 @@
+# ExamForge
+
+Vekkam is now a **CLI-first** multimodal exam-preparation engine built around a canonical Learning IR.
+
+There is no frontend or web server in the runtime path. The CLI is the user-facing product surface; the domain engine remains importable as a Python package.
+
+## Pipeline
+
+```
+SOURCE MATERIAL -> MULTIMODAL EXTRACTION -> CANONICAL LEARNING IR
+-> KNOWLEDGE GRAPH + VECTOR RETRIEVAL -> VISUAL BLUEPRINT
+-> MANIM COMPILER + VALIDATION -> NARRATION + SYNC -> VIDEO
+-> ACTIVE RECALL + FSRS -> EXAM INTELLIGENCE
+```
+
+## CLI
+
+Install locally:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+For PDF/DOCX conversion and Manim rendering:
+
+```bash
+python -m pip install -e ".[document,generation]"
+```
+
+Then:
+
+```bash
+examforge architecture
+examforge llm connect-ollama --model llama3.2:3b
+examforge llm chat "Explain opportunity cost"
+examforge llm connect-api --model gpt-4.1
+examforge ingest-text --file notes.txt
+examforge blueprint --file notes.txt
+examforge questions --file notes.txt --count 4
+examforge video --file ./notes.pdf
+examforge video --file ./chapter.docx --output ./chapter.mp4
+type notes.txt | examforge ingest-text --document-id economics
+```
+
+`video` extracts the PDF/DOCX, sends the extracted learning material through the linked LLM to generate a deterministic Manim scene, validates the returned Python, and renders `ExamForgeScene` to MP4. The generated scene is retained under `.examforge/` beside the requested output.
+
+Every command emits JSON so the CLI can be composed with shell scripts, CI, other tools, or future TUI clients.
+
+### Commands
+
+- `ingest-text`: text -> canonical Learning IR
+- `blueprint`: text/IR-derived concept -> visual teaching blueprint
+- `questions`: concept -> active-recall question set
+- `video`: PDF/DOCX -> LLM-generated Manim scene -> MP4
+- `review`: mastery state -> next review state
+- `architecture`: inspect the engine pipeline
+- `llm connect-api`: link an OpenAI-compatible API using an environment variable for the key
+- `llm connect-ollama`: link a local Ollama server and installed model
+- `llm status`: inspect the active provider without exposing secrets
+- `llm chat`: send a prompt through the active provider
+
+## Repository layout
+
+- `app/core/`: canonical domain models and stable IDs
+- `app/ingestion/`: document/OCR/image extraction
+- `app/visual/`: graph, table and equation understanding
+- `app/knowledge/`: graph and vector-store ports
+- `app/blueprints/`: declarative teaching blueprints
+- `app/manim/`: scene compilation and validation
+- `app/video/`: document-to-Manim video pipeline
+- `app/audio/`: narration and synchronization
+- `app/assessment/`: recall, rescue and mastery
+- `app/cli.py`: product-facing CLI
+- `tests/`: contracts
+- `docs/`: architecture and roadmap
+
+LLM integrations remain isolated behind `app/llm/`; provider configuration is stored locally without storing API keys. API keys are read from environment variables at request time.
+
+Optional integrations remain isolated behind adapters: PyMuPDF/OCR/OpenCV, Neo4j, Qdrant, Manim, Kokoro/Piper and WhisperX.

examforge-0.2.0.post9/app/__main__.py

@@ -0,0 +1,3 @@
+from app.cli import main
+
+raise SystemExit(main())

examforge-0.2.0.post9/app/assessment/mastery.py

@@ -0,0 +1,14 @@
+from datetime import datetime, timedelta
+from app.core.models import MasteryState
+
+def schedule_review(state: MasteryState, recalled: bool) -> MasteryState:
+    now=datetime.utcnow(); state.last_review=now
+    if recalled:
+        state.stability=max(1.0,state.stability*1.35+1.0)
+        state.retrievability=min(1.0,state.retrievability+0.2)
+    else:
+        state.stability=max(0.2,state.stability*0.55)
+        state.retrievability=max(0.0,state.retrievability-0.3)
+    state.next_review=now+timedelta(days=max(1,round(state.stability)))
+    state.review_history.append({"at":now.isoformat(),"recalled":recalled})
+    return state

examforge-0.2.0.post9/app/assessment/quiz.py

@@ -0,0 +1,13 @@
+from app.core.ids import stable_id
+from app.core.models import Concept, Question, QuestionType
+
+def generate_questions(concept: Concept, count: int=4) -> list[Question]:
+    templates=[
+      (QuestionType.recall,f"What is {concept.name}?",concept.description or "State the definition precisely."),
+      (QuestionType.conceptual,f"Explain the central idea behind {concept.name}.",concept.description or "Explain it in your own words."),
+      (QuestionType.application,f"Give one concrete application of {concept.name}.",concept.examples[0] if concept.examples else "Provide a valid application."),
+      (QuestionType.error_detection,f"What is a common mistake when using {concept.name}?","Identify the incorrect assumption and explain why it fails."),
+    ]
+    return [Question(question_id=stable_id("question",concept.concept_id,str(i)),
+                     concept_id=concept.concept_id,type=k,prompt=p,answer=a)
+            for i,(k,p,a) in enumerate(templates[:count])]

examforge-0.2.0.post9/app/audio/sync.py

@@ -0,0 +1,5 @@
+from app.core.models import SceneAction
+
+def build_timeline(actions: list[SceneAction], word_timestamps: list[dict[str,float]]) -> list[dict[str,object]]:
+    return [{"start":a.start,"end":a.end,"action":a.action,
+             "words":[w for w in word_timestamps if a.start<=w["start"]<=a.end]} for a in actions]

examforge-0.2.0.post9/app/blueprints/engine.py

@@ -0,0 +1,15 @@
+from app.core.ids import stable_id
+from app.core.models import Concept, SceneAction, VisualBlueprint
+
+def build_blueprint(concept: Concept) -> VisualBlueprint:
+    scene_type="graph_plot" if concept.visuals else "comparison"
+    return VisualBlueprint(
+        blueprint_id=stable_id("blueprint", concept.concept_id),
+        concept_id=concept.concept_id,
+        scene_type=scene_type,
+        learning_objective=f"Understand {concept.name}",
+        objects=[{"concept_id":concept.concept_id,"name":concept.name}],
+        animations=[SceneAction(start=0,end=2,action="introduce_concept")],
+        narration_cues=[{"at":0,"text":concept.description[:500]}],
+        checkpoint={"type":"active_recall","concept_id":concept.concept_id},
+    )

examforge-0.2.0.post9/app/cli.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from app.assessment.mastery import schedule_review
+from app.assessment.quiz import generate_questions
+from app.blueprints.engine import build_blueprint
+from app.core.models import Concept, MasteryState
+from app.ingestion.text import ingest_text
+from app.llm.client import LLMClient, LLMConfig, config_path, load_config, save_config
+from app.video.pipeline import generate_video
+
+
+def _emit(value: Any) -> None:
+    print(json.dumps(value, indent=2, ensure_ascii=False, default=str))
+
+
+def _read_text(path: str | None, inline: str | None) -> str:
+    if path:
+        return Path(path).read_text(encoding="utf-8")
+    if inline is not None:
+        return inline
+    if not sys.stdin.isatty():
+        return sys.stdin.read()
+    raise SystemExit("Provide --text, --file, or pipe text on stdin.")
+
+
+def _concept(args: argparse.Namespace) -> Concept:
+    document = ingest_text(args.document_id, _read_text(args.file, args.text))
+    if not document.concepts:
+        raise SystemExit("No concepts were produced.")
+    return document.concepts[0]
+
+
+def _review(args: argparse.Namespace) -> None:
+    if not args.state:
+        state = MasteryState(concept_id="concept")
+    else:
+        state = MasteryState.model_validate_json(Path(args.state).read_text(encoding="utf-8"))
+    _emit(schedule_review(state, args.recalled).model_dump(mode="json"))
+
+
+def _video(args: argparse.Namespace) -> None:
+    result = generate_video(args.file, args.output)
+    _emit(
+        {
+            "source": str(result.source_path),
+            "output": str(result.output_path),
+            "scene": str(result.scene_path),
+            "document_id": result.document_id,
+            "provider": result.provider,
+            "model": result.model,
+        }
+    )
+
+
+def _llm_connect_api(args: argparse.Namespace) -> None:
+    config = LLMConfig(provider="api", endpoint=args.endpoint, model=args.model, api_key_env=args.api_key_env)
+    path = save_config(config)
+    _emit({"provider": config.provider, "endpoint": config.endpoint, "model": config.model, "api_key_env": config.api_key_env, "config_path": str(path)})
+
+
+def _llm_connect_ollama(args: argparse.Namespace) -> None:
+    config = LLMConfig(provider="ollama", endpoint=args.endpoint, model=args.model)
+    path = save_config(config)
+    _emit({"provider": config.provider, "endpoint": config.endpoint, "model": config.model, "config_path": str(path)})
+
+
+def _llm_status(_: argparse.Namespace) -> None:
+    config = load_config()
+    if config is None:
+        _emit({"connected": False, "config_path": str(config_path())})
+        return
+    _emit({
+        "connected": True,
+        "provider": config.provider,
+        "endpoint": config.endpoint,
+        "model": config.model,
+        "api_key_env": config.api_key_env,
+        "api_key_configured": bool(config.api_key),
+        "config_path": str(config_path()),
+    })
+
+
+def _llm_chat(args: argparse.Namespace) -> None:
+    config = load_config()
+    if config is None:
+        raise SystemExit("No LLM linked. Run examforge llm connect-api or examforge llm connect-ollama.")
+    response = LLMClient(config).chat(args.prompt, args.system)
+    _emit({"provider": config.provider, "model": config.model, "response": response})
+
+
+def _llm_parser(sub: argparse._SubParsersAction) -> None:
+    llm = sub.add_parser("llm", help="Link ExamForge to an LLM provider.")
+    llm_sub = llm.add_subparsers(dest="llm_command", required=True)
+
+    api = llm_sub.add_parser("connect-api", help="Link an OpenAI-compatible LLM API.")
+    api.add_argument("--endpoint", default="https://api.openai.com/v1")
+    api.add_argument("--model", required=True)
+    api.add_argument("--api-key-env", default="OPENAI_API_KEY", help="Environment variable containing the API key.")
+    api.set_defaults(handler=_llm_connect_api)
+
+    ollama = llm_sub.add_parser("connect-ollama", help="Link a local Ollama server.")
+    ollama.add_argument("--endpoint", default="http://localhost:11434")
+    ollama.add_argument("--model", required=True, help="Installed Ollama model, e.g. llama3.2:3b.")
+    ollama.set_defaults(handler=_llm_connect_ollama)
+
+    status = llm_sub.add_parser("status", help="Show the active LLM connection.")
+    status.set_defaults(handler=_llm_status)
+
+    chat = llm_sub.add_parser("chat", help="Send one prompt through the active LLM.")
+    chat.add_argument("prompt")
+    chat.add_argument("--system")
+    chat.set_defaults(handler=_llm_chat)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="examforge",
+        description="ExamForge CLI: multimodal exam-preparation engine over canonical Learning IR.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    ingest = sub.add_parser("ingest-text", help="Convert text into canonical Learning IR.")
+    ingest.add_argument("--document-id", default="document")
+    ingest.add_argument("--text")
+    ingest.add_argument("--file", help="UTF-8 text file; omit to read stdin.")
+    ingest.set_defaults(
+        handler=lambda a: _emit(
+            ingest_text(a.document_id, _read_text(a.file, a.text)).model_dump(mode="json")
+        )
+    )
+
+    blueprint = sub.add_parser("blueprint", help="Build a visual teaching blueprint from text.")
+    blueprint.add_argument("--document-id", default="document")
+    blueprint.add_argument("--text")
+    blueprint.add_argument("--file")
+    blueprint.set_defaults(handler=lambda a: _emit(build_blueprint(_concept(a)).model_dump(mode="json")))
+
+    questions = sub.add_parser("questions", help="Generate deterministic active-recall questions.")
+    questions.add_argument("--document-id", default="document")
+    questions.add_argument("--text")
+    questions.add_argument("--file")
+    questions.add_argument("--count", type=int, default=4)
+    questions.set_defaults(
+        handler=lambda a: _emit(
+            [q.model_dump(mode="json") for q in generate_questions(_concept(a), a.count)]
+        )
+    )
+
+    video = sub.add_parser("video", help="Convert a PDF or DOCX document into a rendered Manim video.")
+    video.add_argument("--file", required=True, help="Path to a .pdf or .docx document.")
+    video.add_argument("--output", help="Output .mp4 path; defaults to the input filename with .mp4.")
+    video.set_defaults(handler=_video)
+
+    review = sub.add_parser("review", help="Schedule a mastery review from a JSON state.")
+    review.add_argument("--state", help="Path to a MasteryState JSON file.")
+    review.add_argument("--recalled", action="store_true", help="Mark the review as successfully recalled.")
+    review.set_defaults(handler=_review)
+
+    _llm_parser(sub)
+
+    architecture = sub.add_parser("architecture", help="Print the ExamForge pipeline.")
+    architecture.set_defaults(
+        handler=lambda _: _emit(
+            {
+                "source_of_truth": "canonical_learning_ir",
+                "stages": ["multimodal_extraction", "canonical_learning_ir", "knowledge_graph", "vector_retrieval", "visual_blueprint", "manim_validation", "narration_sync", "active_recall", "mastery", "exam_intelligence", "llm_integration"],
+            }
+        )
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    args.handler(args)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

examforge-0.2.0.post9/app/core/ids.py

@@ -0,0 +1,6 @@
+from hashlib import sha256
+
+
+def stable_id(kind: str, *parts: str) -> str:
+    raw = "::".join((kind, *parts))
+    return f"{kind}_{sha256(raw.encode('utf-8')).hexdigest()[:16]}"

examforge-0.2.0.post9/app/core/models.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+from datetime import datetime
+from enum import StrEnum
+from pydantic import BaseModel, Field
+
+class VisualType(StrEnum):
+    text="text"; equation="equation"; graph="graph"; chart="chart"; table="table"
+    diagram="diagram"; flowchart="flowchart"; geometric_figure="geometric_figure"
+    photograph="photograph"; illustration="illustration"; unknown="unknown"
+
+class Reconstructability(StrEnum):
+    reconstructable="RECONSTRUCTABLE"; partial="PARTIALLY_RECONSTRUCTABLE"; none="NON_RECONSTRUCTABLE"
+
+class BoundingBox(BaseModel):
+    x: float; y: float; width: float; height: float
+
+class SourceRegion(BaseModel):
+    page_id: str; bbox: BoundingBox | None=None
+    extracted_text: str | None=None; artifact_path: str | None=None
+
+class VisualObject(BaseModel):
+    id: str; type: str; label: str | None=None; direction: str | None=None
+    source_region: SourceRegion | None=None
+
+class GraphIR(BaseModel):
+    visual_id: str; type: str="graph"; axes: dict[str, object]=Field(default_factory=dict)
+    objects: list[VisualObject]=Field(default_factory=list)
+    intersections: list[dict[str, object]]=Field(default_factory=list)
+    annotations: list[dict[str, object]]=Field(default_factory=list)
+    semantic_interpretation: dict[str, str]=Field(default_factory=dict)
+    reconstructability: Reconstructability=Reconstructability.partial
+    confidence: float=0.0
+
+class EquationIR(BaseModel):
+    latex: str; type: str; variables: list[str]=Field(default_factory=list); operation: str | None=None
+
+class TableIR(BaseModel):
+    columns: list[str]; rows: list[list[object]]
+
+class VisualArtifact(BaseModel):
+    visual_id: str; visual_type: VisualType; source: SourceRegion
+    graph: GraphIR | None=None; equation: EquationIR | None=None; table: TableIR | None=None
+    confidence: float=0.0
+
+class PageIR(BaseModel):
+    page_id: str; page_number: int; text: str=""
+    blocks: list[dict[str, object]]=Field(default_factory=list)
+    figures: list[str]=Field(default_factory=list); tables: list[str]=Field(default_factory=list)
+    equations: list[str]=Field(default_factory=list); visual_regions: list[VisualArtifact]=Field(default_factory=list)
+
+class Concept(BaseModel):
+    concept_id: str; name: str; description: str=""
+    prerequisites: list[str]=Field(default_factory=list); definitions: list[str]=Field(default_factory=list)
+    formulas: list[str]=Field(default_factory=list); examples: list[str]=Field(default_factory=list)
+    visuals: list[str]=Field(default_factory=list); evidence: list[SourceRegion]=Field(default_factory=list)
+
+class LearningDocument(BaseModel):
+    document_id: str; title: str=""; pages: list[PageIR]=Field(default_factory=list)
+    concepts: list[Concept]=Field(default_factory=list); created_at: datetime=Field(default_factory=datetime.utcnow)
+
+class SceneAction(BaseModel):
+    start: float=0.0; end: float=0.0; action: str; payload: dict[str, object]=Field(default_factory=dict)
+
+class VisualBlueprint(BaseModel):
+    blueprint_id: str; concept_id: str; scene_type: str; learning_objective: str
+    objects: list[dict[str, object]]=Field(default_factory=list)
+    animations: list[SceneAction]=Field(default_factory=list)
+    narration_cues: list[dict[str, object]]=Field(default_factory=list)
+    checkpoint: dict[str, object]=Field(default_factory=dict)
+
+class QuestionType(StrEnum):
+    recall="RECALL"; conceptual="CONCEPTUAL"; calculation="CALCULATION"; application="APPLICATION"
+    transfer="TRANSFER"; error_detection="ERROR_DETECTION"; graph_interpretation="GRAPH_INTERPRETATION"
+    diagram_interpretation="DIAGRAM_INTERPRETATION"
+
+class Question(BaseModel):
+    question_id: str; concept_id: str; type: QuestionType; prompt: str; answer: str; explanation: str=""
+
+class QuestionRequest(BaseModel):
+    concept: Concept; count: int=Field(default=4, ge=1, le=20)
+
+class MasteryState(BaseModel):
+    concept_id: str; stability: float=0.0; difficulty: float=0.0; retrievability: float=0.0
+    last_review: datetime | None=None; next_review: datetime | None=None
+    review_history: list[dict[str, object]]=Field(default_factory=list)

examforge-0.2.0.post9/app/ingestion/document.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from app.core.ids import stable_id
+from app.core.models import Concept, LearningDocument, PageIR, SourceRegion
+
+
+def ingest_document(path: Path) -> LearningDocument:
+    """Extract text from a PDF or DOCX while preserving page boundaries where possible."""
+    path = path.expanduser().resolve()
+    suffix = path.suffix.lower()
+    document_id = stable_id("document", str(path))
+    title = path.stem
+
+    if suffix == ".pdf":
+        return _ingest_pdf(path, document_id, title)
+    if suffix == ".docx":
+        return _ingest_docx(path, document_id, title)
+    raise ValueError("Unsupported document type. Use .pdf or .docx.")
+
+
+def _ingest_pdf(path: Path, document_id: str, title: str) -> LearningDocument:
+    try:
+        import fitz
+    except ImportError as exc:
+        raise RuntimeError(
+            "PDF support is not installed. Install the document extra: "
+            "python -m pip install -e '.[document]'"
+        ) from exc
+
+    pages: list[PageIR] = []
+    with fitz.open(path) as pdf:
+        for number, page in enumerate(pdf, start=1):
+            text = page.get_text("text").strip()
+            page_id = stable_id("page", document_id, str(number))
+            pages.append(
+                PageIR(
+                    page_id=page_id,
+                    page_number=number,
+                    text=text,
+                    blocks=[],
+                )
+            )
+
+    return _document(document_id, title, pages)
+
+
+def _ingest_docx(path: Path, document_id: str, title: str) -> LearningDocument:
+    try:
+        from docx import Document
+    except ImportError as exc:
+        raise RuntimeError(
+            "DOCX support is not installed. Install the document extra: "
+            "python -m pip install -e '.[document]'"
+        ) from exc
+
+    document = Document(path)
+    text = "\n".join(
+        paragraph.text.strip()
+        for paragraph in document.paragraphs
+        if paragraph.text.strip()
+    )
+    page_id = stable_id("page", document_id, "1")
+    pages = [PageIR(page_id=page_id, page_number=1, text=text)]
+    return _document(document_id, title, pages)
+
+
+def _document(document_id: str, title: str, pages: list[PageIR]) -> LearningDocument:
+    text = "\n\n".join(page.text for page in pages if page.text.strip())
+    page_id = pages[0].page_id if pages else stable_id("page", document_id, "1")
+    concept = Concept(
+        concept_id=stable_id("concept", document_id, text[:160]),
+        name=title,
+        description=text[:1000],
+        evidence=[
+            SourceRegion(page_id=page_id, extracted_text=text[:4000])
+        ],
+    )
+    return LearningDocument(
+        document_id=document_id,
+        title=title,
+        pages=pages,
+        concepts=[concept] if text else [],
+    )
+
+
+class DocumentIngestor:
+    """Compatibility boundary for document adapters."""
+
+    def ingest(self, path: Path) -> LearningDocument:
+        return ingest_document(path)

examforge-0.2.0.post9/app/ingestion/text.py

@@ -0,0 +1,11 @@
+from app.core.ids import stable_id
+from app.core.models import Concept, LearningDocument, PageIR, SourceRegion
+
+def ingest_text(document_id: str, text: str) -> LearningDocument:
+    page_id = stable_id("page", document_id, "1")
+    concept_id = stable_id("concept", document_id, text[:160])
+    concept = Concept(concept_id=concept_id, name="Imported concept", description=text[:1000],
+                      evidence=[SourceRegion(page_id=page_id, extracted_text=text[:4000])])
+    return LearningDocument(document_id=document_id, title=document_id,
+                            pages=[PageIR(page_id=page_id, page_number=1, text=text)],
+                            concepts=[concept])

examforge-0.2.0.post9/app/knowledge/in_memory.py

@@ -0,0 +1,15 @@
+from app.core.models import Concept
+
+class InMemoryKnowledgeGraph:
+    def __init__(self): self.nodes={}; self.edges=[]
+    def upsert_concept(self, concept: Concept) -> None: self.nodes[concept.concept_id]=concept
+    def add_edge(self, source: str, relation: str, target: str) -> None: self.edges.append((source,relation,target))
+
+class InMemoryVectorStore:
+    def __init__(self): self.items=[]
+    def upsert(self, document_id: str, text: str, metadata: dict[str,str]) -> None:
+        self.items.append({"id":document_id,"text":text,"metadata":metadata})
+    def search(self, query: str, limit: int=5) -> list[dict[str,object]]:
+        terms=set(query.lower().split())
+        ranked=sorted(self.items,key=lambda x:len(terms & set(str(x["text"]).lower().split())),reverse=True)
+        return ranked[:limit]

examforge-0.2.0.post9/app/knowledge/ports.py

@@ -0,0 +1,10 @@
+from typing import Protocol
+from app.core.models import Concept
+
+class KnowledgeGraph(Protocol):
+    def upsert_concept(self, concept: Concept) -> None: ...
+    def add_edge(self, source: str, relation: str, target: str) -> None: ...
+
+class VectorStore(Protocol):
+    def upsert(self, document_id: str, text: str, metadata: dict[str,str]) -> None: ...
+    def search(self, query: str, limit: int=5) -> list[dict[str,object]]: ...

examforge-0.2.0.post9/app/llm/client.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+_CONFIG_DIR = Path.home() / ".config" / "examforge"
+_CONFIG_FILE = _CONFIG_DIR / "llm.json"
+
+@dataclass(frozen=True)
+class LLMConfig:
+    provider: str
+    endpoint: str
+    model: str
+    api_key_env: str | None = None
+
+    @property
+    def api_key(self) -> str | None:
+        return os.getenv(self.api_key_env) if self.api_key_env else None
+
+def save_config(config: LLMConfig) -> Path:
+    _CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    _CONFIG_FILE.write_text(
+        json.dumps(
+            {
+                "provider": config.provider,
+                "endpoint": config.endpoint,
+                "model": config.model,
+                "api_key_env": config.api_key_env,
+            },
+            indent=2,
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    return _CONFIG_FILE
+
+def load_config() -> LLMConfig | None:
+    if not _CONFIG_FILE.exists():
+        return None
+    data = json.loads(_CONFIG_FILE.read_text(encoding="utf-8"))
+    return LLMConfig(
+        provider=data["provider"],
+        endpoint=data["endpoint"],
+        model=data["model"],
+        api_key_env=data.get("api_key_env"),
+    )
+
+class LLMClient:
+    """Small dependency-free client for Ollama and OpenAI-compatible APIs."""
+
+    def __init__(self, config: LLMConfig):
+        self.config = config
+
+    def _post(self, url: str, payload: dict[str, object], headers: dict[str, str] | None = None) -> dict[str, object]:
+        body = json.dumps(payload).encode("utf-8")
+        request = Request(url, data=body, method="POST")
+        request.add_header("Content-Type", "application/json")
+        for key, value in (headers or {}).items():
+            request.add_header(key, value)
+        try:
+            with urlopen(request, timeout=120) as response:
+                return json.loads(response.read().decode("utf-8"))
+        except HTTPError as exc:
+            detail = exc.read().decode("utf-8", errors="replace")
+            raise RuntimeError(f"LLM request failed ({exc.code}): {detail}") from exc
+        except URLError as exc:
+            raise RuntimeError(f"Could not reach LLM at {url}: {exc.reason}") from exc
+
+    def chat(self, prompt: str, system: str | None = None) -> str:
+        messages: list[dict[str, str]] = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+
+        if self.config.provider == "ollama":
+            payload = {"model": self.config.model, "messages": messages, "stream": False}
+            result = self._post(self.config.endpoint.rstrip("/") + "/api/chat", payload)
+            return str(result["message"]["content"])
+
+        headers = {}
+        if self.config.api_key:
+            headers["Authorization"] = f"Bearer {self.config.api_key}"
+        payload = {"model": self.config.model, "messages": messages, "stream": False}
+        result = self._post(self.config.endpoint.rstrip("/") + "/chat/completions", payload, headers)
+        return str(result["choices"][0]["message"]["content"])
+
+def config_path() -> Path:
+    return _CONFIG_FILE

examforge-0.2.0.post9/app/manim/compiler.py

@@ -0,0 +1,17 @@
+from dataclasses import dataclass
+from app.core.models import VisualBlueprint
+
+@dataclass
+class CompilationResult:
+    valid: bool
+    source: str
+    errors: list[str]
+
+class ManimCompiler:
+    """Blueprint -> template -> Manim source. The LLM never owns this interface."""
+    def compile(self, blueprint: VisualBlueprint) -> CompilationResult:
+        source=("from manim import *\n\nclass ExamForgeScene(Scene):\n"
+                "    def construct(self):\n"
+                f"        title = Text({blueprint.learning_objective!r})\n"
+                "        self.play(Write(title))\n        self.wait(1)\n")
+        return CompilationResult(True, source, [])

examforge-0.2.0.post9/app/manim/validation.py

@@ -0,0 +1,15 @@
+from dataclasses import dataclass
+from app.core.models import VisualBlueprint
+
+@dataclass
+class ValidationReport:
+    code_valid: bool
+    render_valid: bool
+    pedagogical_valid: bool
+    errors: list[str]
+
+def validate_blueprint(blueprint: VisualBlueprint) -> ValidationReport:
+    errors=[]
+    if not blueprint.learning_objective.strip(): errors.append("Missing learning objective.")
+    if not blueprint.animations: errors.append("Blueprint contains no animation actions.")
+    return ValidationReport(not errors, False, not errors, errors)

examforge-0.2.0.post9/app/video/__init__.py

@@ -0,0 +1 @@
+"""Document-to-Manim video generation pipeline."""

examforge-0.2.0.post9/app/video/pipeline.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+import ast
+import re
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from app.ingestion.document import ingest_document
+from app.llm.client import LLMClient, load_config
+
+_ALLOWED_CLASS_PATTERN = re.compile(r"class\s+ExamForgeScene\s*\(\s*Scene\s*\)")
+
+
+@dataclass(frozen=True)
+class VideoResult:
+    source_path: Path
+    output_path: Path
+    scene_path: Path
+    document_id: str
+    provider: str
+    model: str
+
+
+def _extract_code(response: str) -> str:
+    match = re.search(r"```(?:python)?\s*(.*?)```", response, re.DOTALL | re.IGNORECASE)
+    return match.group(1).strip() if match else response.strip()
+
+
+def _validate_source(source: str) -> None:
+    try:
+        tree = ast.parse(source)
+    except SyntaxError as exc:
+        raise RuntimeError(f"LLM returned invalid Python: {exc}") from exc
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            raise RuntimeError("Generated source may only import from manim.")
+        if isinstance(node, ast.ImportFrom) and node.module != "manim":
+            raise RuntimeError("Generated source may only import from manim.")
+        if isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id in {
+            "eval", "exec", "open", "compile", "__import__", "input"
+        }:
+            raise RuntimeError(f"Generated source uses forbidden function: {node.func.id}")
+        if isinstance(node, ast.Name) and node.id in {
+            "os", "sys", "subprocess", "pathlib", "socket", "requests"
+        }:
+            raise RuntimeError(f"Generated source uses forbidden module/name: {node.id}")
+
+    if not _ALLOWED_CLASS_PATTERN.search(source):
+        raise RuntimeError("Generated Manim source must define an ExamForgeScene(Scene) class.")
+
+    classes = [node for node in tree.body if isinstance(node, ast.ClassDef)]
+    if not any(node.name == "ExamForgeScene" for node in classes):
+        raise RuntimeError("Generated source does not contain ExamForgeScene.")
+
+
+def _prompt(title: str, text: str) -> str:
+    return f"""Create a concise educational Manim Community Edition video from the document below.
+
+Document title: {title}
+
+Requirements:
+- Return ONLY complete Python source code.
+- Import from manim with: from manim import *
+- Define exactly one main scene named ExamForgeScene(Scene).
+- Teach the most important concepts in a clear sequence using Text, MathTex, axes, shapes, arrows, and simple animations where useful.
+- Prefer deterministic, readable Manim primitives over external assets.
+- Keep rendering practical: target roughly 30-90 seconds and avoid expensive simulations.
+- Do not use network access, file I/O, subprocesses, eval, exec, or arbitrary imports.
+- Escape text safely and use MathTex only for valid LaTeX.
+- The scene must run with standard Manim Community Edition.
+
+DOCUMENT:
+{text[:30000]}
+"""
+
+
+def generate_video(
+    source_path: str | Path,
+    output_path: str | Path | None = None,
+) -> VideoResult:
+    source = Path(source_path).expanduser().resolve()
+    if not source.exists() or not source.is_file():
+        raise FileNotFoundError(f"Input file not found: {source}")
+    if source.suffix.lower() not in {".pdf", ".docx"}:
+        raise ValueError("Input must be a .pdf or .docx file.")
+
+    config = load_config()
+    if config is None:
+        raise RuntimeError(
+            "No LLM linked. Run examforge llm connect-api or "
+            "examforge llm connect-ollama first."
+        )
+
+    document = ingest_document(source)
+    if not document.pages:
+        raise RuntimeError("No readable content was extracted from the document.")
+
+    text = "\n\n".join(page.text for page in document.pages if page.text.strip())
+    if not text.strip():
+        raise RuntimeError("The document contains no extractable text.")
+
+    response = LLMClient(config).chat(_prompt(document.title, text))
+    manim_source = _extract_code(response)
+    _validate_source(manim_source)
+
+    target = Path(output_path).expanduser() if output_path else source.with_suffix(".mp4")
+    target = target.resolve()
+    target.parent.mkdir(parents=True, exist_ok=True)
+
+    scene_dir = target.parent / ".examforge" / source.stem
+    scene_dir.mkdir(parents=True, exist_ok=True)
+    scene_path = scene_dir / "scene.py"
+    scene_path.write_text(manim_source + "\n", encoding="utf-8")
+
+    command = [
+        sys.executable, "-m", "manim", "-q", "m", str(scene_path), "ExamForgeScene",
+        "--media_dir", str(scene_dir / "media"), "-o", target.name,
+    ]
+    try:
+        completed = subprocess.run(command, check=True, capture_output=True, text=True)
+    except FileNotFoundError as exc:
+        raise RuntimeError(
+            "Manim is not installed. Install the generation extra: "
+            "python -m pip install -e '.[generation]'"
+        ) from exc
+    except subprocess.CalledProcessError as exc:
+        detail = (exc.stderr or exc.stdout or "unknown Manim error").strip()
+        raise RuntimeError(f"Manim render failed: {detail}") from exc
+
+    rendered = scene_dir / "media" / "videos" / "scene" / "720p30" / target.name
+    if rendered.exists() and rendered != target:
+        target.write_bytes(rendered.read_bytes())
+    elif not target.exists():
+        candidates = list((scene_dir / "media").rglob(target.name))
+        if candidates:
+            target.write_bytes(candidates[0].read_bytes())
+
+    if not target.exists():
+        raise RuntimeError(
+            "Manim completed without producing the expected video output. "
+            f"stdout: {completed.stdout[-1000:]}"
+        )
+
+    return VideoResult(
+        source_path=source,
+        output_path=target,
+        scene_path=scene_path,
+        document_id=document.document_id,
+        provider=config.provider,
+        model=config.model,
+    )

examforge-0.2.0.post9/app/visual/equation.py

@@ -0,0 +1,6 @@
+import re
+from app.core.models import EquationIR
+
+def parse_equation(latex: str, equation_type: str="unknown", operation: str|None=None) -> EquationIR:
+    variables=sorted(set(re.findall(r"(?<![A-Za-z])[A-Za-z](?![A-Za-z])", latex)))
+    return EquationIR(latex=latex, type=equation_type, variables=variables, operation=operation)

examforge-0.2.0.post9/app/visual/graph.py

@@ -0,0 +1,10 @@
+from app.core.models import GraphIR, Reconstructability, VisualObject
+
+def interpret_graph(visual_id: str, x_label: str, y_label: str,
+                    objects: list[tuple[str, str, str]]) -> GraphIR:
+    parsed=[VisualObject(id=f"{visual_id}_{label.lower()}", type=kind, label=label, direction=direction)
+            for label, kind, direction in objects]
+    return GraphIR(visual_id=visual_id,
+                   axes={"x":{"label":x_label,"scale":"unknown"},"y":{"label":y_label,"scale":"unknown"}},
+                   objects=parsed, reconstructability=Reconstructability.reconstructable,
+                   confidence=0.9 if parsed else 0.5)

examforge-0.2.0.post9/app/visual/table.py

@@ -0,0 +1,6 @@
+from app.core.models import TableIR
+
+def parse_table(columns: list[str], rows: list[list[object]]) -> TableIR:
+    if any(len(row)!=len(columns) for row in rows):
+        raise ValueError("Every table row must match the column count.")
+    return TableIR(columns=columns, rows=rows)

examforge-0.2.0.post9/examforge.egg-info/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: examforge
+Version: 0.2.0.post9
+Summary: CLI-first multimodal exam-preparation engine with a canonical learning IR
+Requires-Python: >=3.12
+Requires-Dist: pydantic<3,>=2.8
+Provides-Extra: document
+Requires-Dist: pymupdf>=1.24; extra == "document"
+Requires-Dist: pymupdf4llm>=0.0.17; extra == "document"
+Requires-Dist: python-docx>=1.1; extra == "document"
+Requires-Dist: pytesseract>=0.3.13; extra == "document"
+Requires-Dist: opencv-python>=4.10; extra == "document"
+Provides-Extra: knowledge
+Requires-Dist: neo4j>=5.25; extra == "knowledge"
+Requires-Dist: qdrant-client>=1.12; extra == "knowledge"
+Provides-Extra: generation
+Requires-Dist: manim>=0.18; extra == "generation"
+Provides-Extra: audio
+Requires-Dist: openai-whisper>=20240930; extra == "audio"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.13; extra == "dev"

examforge-0.2.0.post9/examforge.egg-info/SOURCES.txt

@@ -0,0 +1,41 @@
+README.md
+pyproject.toml
+app/__init__.py
+app/__main__.py
+app/cli.py
+app/assessment/__init__.py
+app/assessment/mastery.py
+app/assessment/quiz.py
+app/audio/__init__.py
+app/audio/sync.py
+app/blueprints/__init__.py
+app/blueprints/engine.py
+app/core/__init__.py
+app/core/ids.py
+app/core/models.py
+app/ingestion/__init__.py
+app/ingestion/document.py
+app/ingestion/text.py
+app/knowledge/__init__.py
+app/knowledge/in_memory.py
+app/knowledge/ports.py
+app/llm/client.py
+app/manim/__init__.py
+app/manim/compiler.py
+app/manim/validation.py
+app/video/__init__.py
+app/video/pipeline.py
+app/visual/__init__.py
+app/visual/equation.py
+app/visual/graph.py
+app/visual/table.py
+examforge.egg-info/PKG-INFO
+examforge.egg-info/SOURCES.txt
+examforge.egg-info/dependency_links.txt
+examforge.egg-info/entry_points.txt
+examforge.egg-info/requires.txt
+examforge.egg-info/top_level.txt
+tests/test_cli.py
+tests/test_document_video.py
+tests/test_ids.py
+tests/test_visual.py

examforge-0.2.0.post9/examforge.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

examforge-0.2.0.post9/examforge.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+examforge = app.cli:main

examforge-0.2.0.post9/examforge.egg-info/requires.txt

@@ -0,0 +1,24 @@
+pydantic<3,>=2.8
+
+[audio]
+openai-whisper>=20240930
+
+[dev]
+pytest>=8.3
+httpx>=0.27
+ruff>=0.6
+mypy>=1.13
+
+[document]
+pymupdf>=1.24
+pymupdf4llm>=0.0.17
+python-docx>=1.1
+pytesseract>=0.3.13
+opencv-python>=4.10
+
+[generation]
+manim>=0.18
+
+[knowledge]
+neo4j>=5.25
+qdrant-client>=1.12

examforge-0.2.0.post9/examforge.egg-info/top_level.txt

@@ -0,0 +1 @@
+app

examforge-0.2.0.post9/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "examforge"
+version = "0.2.0.post9"
+description = "CLI-first multimodal exam-preparation engine with a canonical learning IR"
+requires-python = ">=3.12"
+dependencies = ["pydantic>=2.8,<3"]
+
+[project.optional-dependencies]
+document = ["pymupdf>=1.24", "pymupdf4llm>=0.0.17", "python-docx>=1.1", "pytesseract>=0.3.13", "opencv-python>=4.10"]
+knowledge = ["neo4j>=5.25", "qdrant-client>=1.12"]
+generation = ["manim>=0.18"]
+audio = ["openai-whisper>=20240930"]
+dev = ["pytest>=8.3", "httpx>=0.27", "ruff>=0.6", "mypy>=1.13"]
+
+[project.scripts]
+examforge = "app.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["app*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.mypy]
+python_version = "3.12"
+strict = true

examforge-0.2.0.post9/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

examforge-0.2.0.post9/tests/test_cli.py

@@ -0,0 +1,25 @@
+from app.cli import main
+
+
+def test_architecture_command(capsys):
+    assert main(["architecture"]) == 0
+    assert "canonical_learning_ir" in capsys.readouterr().out
+
+
+def test_ingest_text_command(capsys):
+    assert main(["ingest-text", "--document-id", "demo", "--text", "Supply and demand"]) == 0
+    output = capsys.readouterr().out
+    assert '"document_id": "demo"' in output
+
+
+def test_llm_connect_ollama(capsys, monkeypatch, tmp_path):
+    import app.llm.client as client
+
+    monkeypatch.setattr(client, "_CONFIG_DIR", tmp_path)
+    monkeypatch.setattr(client, "_CONFIG_FILE", tmp_path / "llm.json")
+    assert main(["llm", "connect-ollama", "--model", "llama3.2:3b"]) == 0
+    output = capsys.readouterr().out
+    assert '"provider": "ollama"' in output
+    assert '"model": "llama3.2:3b"' in output
+    assert main(["llm", "status"]) == 0
+    assert '"connected": true' in capsys.readouterr().out

examforge-0.2.0.post9/tests/test_document_video.py

@@ -0,0 +1,32 @@
+from pathlib import Path
+
+import pytest
+
+from app.ingestion.document import ingest_document
+from app.video.pipeline import _extract_code, _validate_source
+
+
+def test_extract_code_block():
+    source = "```python\nfrom manim import *\nclass ExamForgeScene(Scene):\n    pass\n```"
+    assert _extract_code(source).startswith("from manim import *")
+
+
+def test_validate_source_accepts_scene():
+    _validate_source("from manim import *\nclass ExamForgeScene(Scene):\n    def construct(self):\n        pass\n")
+
+
+def test_validate_source_rejects_invalid_python():
+    with pytest.raises(RuntimeError, match="invalid Python"):
+        _validate_source("class ExamForgeScene(Scene):\n    def construct(")
+
+
+def test_validate_source_rejects_wrong_scene_name():
+    with pytest.raises(RuntimeError, match="ExamForgeScene"):
+        _validate_source("from manim import *\nclass OtherScene(Scene):\n    pass\n")
+
+
+def test_ingest_document_rejects_unknown_suffix(tmp_path: Path):
+    source = tmp_path / "notes.txt"
+    source.write_text("hello", encoding="utf-8")
+    with pytest.raises(ValueError, match="\\.pdf or \\.docx"):
+        ingest_document(source)

examforge-0.2.0.post9/tests/test_ids.py

@@ -0,0 +1,5 @@
+from app.core.ids import stable_id
+
+def test_stable_ids_are_deterministic():
+    assert stable_id("concept","doc","equilibrium")==stable_id("concept","doc","equilibrium")
+    assert stable_id("concept","doc","equilibrium")!=stable_id("concept","doc","elasticity")

examforge-0.2.0.post9/tests/test_visual.py

@@ -0,0 +1,14 @@
+from app.visual.equation import parse_equation
+from app.visual.graph import interpret_graph
+from app.visual.table import parse_table
+
+def test_equation_ir():
+    eq=parse_equation(r"\frac{d}{dx}x^2 = 2x","derivative","differentiation")
+    assert eq.operation=="differentiation" and "x" in eq.variables
+
+def test_graph_ir():
+    graph=interpret_graph("fig_1","Quantity","Price",[("D","curve","negative"),("S","curve","positive")])
+    assert graph.reconstructability.value=="RECONSTRUCTABLE" and len(graph.objects)==2
+
+def test_table_ir():
+    assert parse_table(["Year","GDP"],[[2024,100]]).rows[0][1]==100