codelith 0.1.0__py3-none-any.whl

backend/__init__.py

@@ -0,0 +1 @@
+"""CodeLith backend package."""

backend/agents/__init__.py

@@ -0,0 +1,6 @@
+"""CodeLith agents — autonomous workers that handle specific tasks.
+
+- coding_agent: reads/writes files, runs commands, builds features.
+- debug_agent: runs tests, diagnoses failures, fixes code.
+- teacher_agent: analyzes code for concepts and teaches the user.
+"""

backend/agents/assessment_agent.py

@@ -0,0 +1,273 @@
+"""Assessment Agent — generates Socratic questions based on detected concepts.
+
+When the coding agent uses a programming concept (e.g. useState, async/await),
+this agent generates a question to test the user's understanding.  Questions
+are stored for the dashboard to display — not printed in the terminal.
+
+Concept detection itself happens upstream in the shared ``detect_concepts``
+node (see :mod:`backend.agents.concept_detector`); this node reads the shared
+``concepts_detected`` result instead of re-scanning tool calls.
+
+The teacher agent then saves the teaching content to the dashboard as well.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from langchain_core.messages import AIMessage, BaseMessage, HumanMessage
+from backend.llm.client import DEFAULT_MODEL, resolve_api_key, get_client  # noqa: F401 (DEFAULT_MODEL re-exported)
+from backend.llm.config import get_model
+
+# ---------------------------------------------------------------------------
+# Socratic question templates
+# ---------------------------------------------------------------------------
+
+QUESTION_TEMPLATES: dict[str, list[str]] = {
+    "useState": [
+        "Why are we using useState here instead of a regular variable?",
+        "What happens when we call the setter function from useState?",
+        "When would you NOT want to use useState?",
+    ],
+    "useEffect": [
+        "What does the dependency array control in this useEffect?",
+        "Why do we need a cleanup function here?",
+        "What happens if we omit the dependency array entirely?",
+    ],
+    "useMemo": [
+        "What problem does useMemo solve in this component?",
+        "How does useMemo differ from just calling the function directly?",
+        "When would useMemo actually hurt performance instead of helping?",
+    ],
+    "useCallback": [
+        "Why are we wrapping this function in useCallback?",
+        "What would happen if we passed the function directly without useCallback?",
+        "When is useCallback unnecessary?",
+    ],
+    "useRef": [
+        "Why use useRef instead of useState for this value?",
+        "What's the key difference between useRef and useState in terms of re-renders?",
+        "When would you reach for useRef over useState?",
+    ],
+    "useContext": [
+        "What problem does useContext solve compared to prop drilling?",
+        "When might useContext cause performance issues?",
+        "How does the context value get updated?",
+    ],
+    "async/await": [
+        "Why do we use async/await here instead of .then() chains?",
+        "What happens if we forget to await this promise?",
+        "How does error handling work with async/await?",
+    ],
+    "Promises": [
+        "What are the three states of a Promise?",
+        "How does Promise.all differ from Promise.race?",
+        "What happens when a Promise rejects and we don't catch it?",
+    ],
+    "Default Export": [
+        "What's the difference between a default export and a named export?",
+        "Why might you choose one over the other?",
+        "Can a file have multiple default exports?",
+    ],
+    "TypeScript Interface": [
+        "What's the difference between an interface and a type alias?",
+        "Why define an interface if TypeScript can infer types?",
+        "When would you extend an interface instead of using intersection types?",
+    ],
+    "Python OOP": [
+        "Why do we use __init__ instead of a constructor method?",
+        "What does 'self' represent in a Python class?",
+        "When would you use a class method vs an instance method?",
+    ],
+    "Error Handling": [
+        "Why wrap this code in try/except instead of letting it fail?",
+        "What's the difference between catching Exception vs a specific error?",
+        "When is it better to let an exception propagate instead of catching it?",
+    ],
+    "Decorators": [
+        "What does this decorator modify about the function's behavior?",
+        "How does @decorator syntax differ from calling decorator(func) directly?",
+        "When might you write a custom decorator vs using a built-in one?",
+    ],
+    "Lambda Functions": [
+        "Why use a lambda here instead of a regular function?",
+        "What are the limitations of lambda functions in Python?",
+        "When would you prefer a named function over a lambda?",
+    ],
+    "Imports / Modules": [
+        "What's the difference between 'import module' and 'from module import X'?",
+        "Why might you use __init__.py in a package?",
+        "When would you use a relative vs absolute import?",
+    ],
+    "Classes / OOP": [
+        "Why use a class here instead of a module with functions?",
+        "What does inheritance give us that composition doesn't?",
+        "When is composition preferred over inheritance?",
+    ],
+    "map()": [
+        "Why use map() instead of a for loop here?",
+        "What's the difference between map() and a list comprehension?",
+        "When might a for loop be clearer than map()?",
+    ],
+    "filter()": [
+        "What does the predicate function need to return for filter()?",
+        "How does filter() differ from using a list comprehension with if?",
+        "When would you use filter() vs a for loop with conditionals?",
+    ],
+    "Fetch API": [
+        "Why use fetch() instead of XMLHttpRequest?",
+        "What happens if we don't await the fetch response?",
+        "How does error handling differ between fetch and traditional AJAX?",
+    ],
+    "DOM Querying": [
+        "Why querySelector instead of getElementById?",
+        "What's the difference between querySelector and querySelectorAll?",
+        "When might direct DOM manipulation be better than a framework?",
+    ],
+    "Event Listeners": [
+        "Why register an event listener instead of using inline HTML handlers?",
+        "What's the difference between addEventListener and onclick?",
+        "When would you remove an event listener?",
+    ],
+}
+
+# Fallback generic questions for concepts not in the template
+GENERIC_QUESTIONS = [
+    "Why did we use {concept_name} here?",
+    "What problem does {concept_name} solve in this context?",
+    "When would you choose {concept_name} over alternatives?",
+]
+
+
+@dataclass
+class Assessment:
+    """A pending assessment question for the user."""
+
+    id: str
+    concept_name: str
+    concept_category: str
+    question: str
+    source_file: str
+    answered: bool = False
+    answer: str = ""
+    correct: bool = False
+
+
+def _generate_assessment_id(concept_name: str, source_file: str) -> str:
+    """Generate a stable ID for an assessment based on concept + file."""
+    import hashlib
+    raw = f"{concept_name}:{source_file}"
+    return hashlib.md5(raw.encode()).hexdigest()[:12]
+
+
+def _get_question(concept_name: str) -> str:
+    """Return a Socratic question for the given concept."""
+    import random
+    templates = QUESTION_TEMPLATES.get(concept_name, GENERIC_QUESTIONS)
+    template = random.choice(templates)
+    return template.format(concept_name=concept_name)
+
+
+# ---------------------------------------------------------------------------
+# Assessment Agent node (for LangGraph)
+# ---------------------------------------------------------------------------
+
+
+def assessment_agent_node(state: dict[str, Any]) -> dict[str, Any]:
+    """LangGraph node: generate Socratic questions for newly detected concepts.
+
+    The frequency of questions depends on the session mode:
+    - ``learn``: question for every new concept (high frequency)
+    - ``pair-programming``: question for roughly 1 in 3 new concepts (low)
+    - ``autonomous``: no questions at all (the graph also skips this node
+      when the mode disables assessment)
+
+    Expects ``state["concepts_detected"]`` — written by the shared
+    detect_concepts node (registry scan + mode-gated LLM detection).
+    Expects ``state["concepts"]`` for already-known concepts.
+    Expects ``state["session"]`` for storage.
+    Expects ``state["current_mode_config"]`` for mode settings.
+
+    Returns:
+        - ``pending_assessments``: list of Assessment dicts for the dashboard
+        - ``messages``: appends an assessment prompt message
+    """
+    import random as _random
+
+    from backend.database.concepts import get_all_assessments, save_assessment
+
+    detected: list[dict[str, Any]] = state.get("concepts_detected", [])
+    concepts: list[dict[str, Any]] = state.get("concepts", [])
+    session: str = state.get("session", "default")
+    messages: list[BaseMessage] = state.get("messages", [])
+
+    # Determine assessment frequency from mode config
+    mode_config: dict[str, Any] | None = state.get("current_mode_config")
+    if mode_config is not None:
+        freq = mode_config.get("assessment_frequency", "high")
+    else:
+        freq = "high"  # default to generating questions
+
+    # In autonomous mode, skip question generation entirely
+    if freq == "none":
+        return {}
+
+    # Filter to only NEW concepts (not already known).  Detection already
+    # ran upstream in the shared detect_concepts node (registry scan +
+    # mode-gated LLM detection), so no re-scanning of tool calls here.
+    new_concepts = [c for c in detected if c["name"] not in {cc["name"] for cc in concepts}]
+
+    if not new_concepts:
+        return {}
+
+    # In low-frequency mode (pair-programming), only ask about ~1 in 3 concepts
+    if freq == "low" and len(new_concepts) > 1:
+        new_concepts = [c for c in new_concepts if _random.random() < 0.34]
+        if not new_concepts:
+            return {}
+
+    # Avoid duplicates against every stored assessment (queued or not)
+    existing = get_all_assessments(session)
+    existing_ids = {a["id"] for a in existing}
+
+    pending: list[dict[str, Any]] = []
+    for concept in new_concepts:
+        concept_name = concept["name"]
+        concept_source = concept.get("source_file", "")
+        assessment_id = _generate_assessment_id(concept_name, concept_source)
+        if assessment_id in existing_ids:
+            continue
+
+        question = _get_question(concept_name)
+        assessment = {
+            "id": assessment_id,
+            "concept_name": concept_name,
+            "concept_category": concept["category"],
+            "question": question,
+            "source_file": concept_source,
+            "answered": False,
+            "answer": "",
+            "correct": False,
+        }
+        save_assessment(session, assessment)
+        pending.append(assessment)
+
+    if not pending:
+        return {}
+
+    # Build a message that points the user to the dashboard instead of
+    # dumping concepts/questions into the terminal.  Questions are surfaced
+    # one at a time there; the rest stay queued in the backend.
+    assessment_msg = (
+        f"New coding concept(s) detected! They're available with "
+        f"explanations on the dashboard (Concepts section). "
+        f"I've also prepared {len(pending)} question(s) for you — check the "
+        f"**Assessment Questions** section on the dashboard to answer them; "
+        f"they're asked one at a time."
+    )
+
+    return {
+        "messages": messages + [AIMessage(content=assessment_msg)],
+        "pending_assessments": pending,
+    }