codelith 0.1.0__py3-none-any.whl

backend/agents/debug_agent.py

@@ -0,0 +1,166 @@
+"""Debug Agent — runs tests, reads errors, fixes code, re-runs.
+
+This agent is invoked when tests fail.  It enters a loop:
+
+    Run tests → read error → fix code → run tests → repeat
+
+It uses the same tool infrastructure as the coding agent (read_file,
+write_file, edit_file, run_command) but has a tighter system prompt
+focused on debugging and a capped retry count to avoid infinite loops.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from langchain_core.messages import AIMessage, BaseMessage, HumanMessage
+
+from backend.agents.coding_agent import (
+    MAX_OUTPUT_SIZE,
+    MAX_TOOL_ROUNDS,
+    MAX_WRITE_SIZE,
+    COMMAND_TIMEOUT,
+    TOOL_DEFINITIONS,
+    _create_with_retry,
+    _parse_tool_args,
+    _read_file,
+    _write_file,
+    _edit_file,
+    _run_command,
+    workspace_context,
+)
+from backend.llm.client import (
+    AGENT_MAX_TOKENS,
+    resolve_agent_api_key,
+    get_agent_client,
+)
+from backend.llm.config import get_model
+
+# ---------------------------------------------------------------------------
+# System prompt
+# ---------------------------------------------------------------------------
+
+SYSTEM_PROMPT = """You are a debug agent. Fix failing tests. Read the error, find the source, fix it, re-run tests. Use tools. Keep replies short."""
+
+# ---------------------------------------------------------------------------
+# Agent node
+# ---------------------------------------------------------------------------
+
+
+def debug_agent_node(state: dict[str, Any]) -> dict[str, Any]:
+    """LangGraph node: run tests, diagnose failures, fix code, re-run.
+
+    Expects ``state["messages"]`` to contain the prior conversation (the
+    coding agent's work and the test output that triggered this node).
+    Expects ``state["workspace_root"]`` to be a string path.
+
+    Returns updated ``messages`` with the debug agent's reply.
+    """
+    messages: list[BaseMessage] = state.get("messages", [])
+    workspace_root: str = state.get("workspace_root", os.getcwd())
+
+    api_key = resolve_agent_api_key()
+    if not api_key:
+        reply = (
+            "Debug agent needs an OpenRouter API key. Set OPENROUTER_API_KEY "
+            "environment variable and try again."
+        )
+        return {"messages": messages + [AIMessage(content=reply)]}
+
+    try:
+        client = get_agent_client()
+    except ValueError as exc:
+        return {"messages": messages + [AIMessage(content=str(exc))]}
+
+    # Build the conversation.  The ENVIRONMENT block grounds the agent in
+    # the real workspace root and shell, like the coding agent.
+    api_messages: list[dict[str, Any]] = [
+        {"role": "system", "content": SYSTEM_PROMPT + workspace_context(workspace_root)}
+    ]
+    for msg in messages:
+        if isinstance(msg, HumanMessage):
+            api_messages.append({"role": "user", "content": msg.content})
+        elif isinstance(msg, AIMessage):
+            api_messages.append({"role": "assistant", "content": msg.content})
+
+    # Tool-use loop — same as coding agent but scoped to debugging.
+    for _ in range(MAX_TOOL_ROUNDS):
+        try:
+            completion = _create_with_retry(client, api_messages)
+        except Exception as exc:
+            reply_text = f"(LLM error: {exc})"
+            return {"messages": messages + [AIMessage(content=reply_text)]}
+
+        choice = completion.choices[0]
+        message = choice.message
+
+        if message.tool_calls:
+            assistant_msg: dict[str, Any] = {
+                "role": "assistant",
+                "content": message.content,
+                "tool_calls": [
+                    {
+                        "id": tc.id,
+                        "type": "function",
+                        "function": {
+                            "name": tc.function.name,
+                            "arguments": tc.function.arguments,
+                        },
+                    }
+                    for tc in message.tool_calls
+                ],
+            }
+            api_messages.append(assistant_msg)
+
+            for tool_call in message.tool_calls:
+                fn = tool_call.function
+
+                args = _parse_tool_args(fn.arguments)
+                if not args:
+                    result = (
+                        f"Error: could not parse arguments for '{fn.name}' "
+                        "as JSON. Re-emit the tool call with valid JSON arguments."
+                    )
+                elif fn.name == "read_file":
+                    result = _read_file(
+                        args.get("file_path", ""),
+                        workspace_root,
+                    )
+                elif fn.name == "write_file":
+                    result = _write_file(
+                        args.get("file_path", ""),
+                        args.get("content", ""),
+                        workspace_root,
+                    )
+                elif fn.name == "edit_file":
+                    result = _edit_file(
+                        args.get("file_path", ""),
+                        args.get("old_string", ""),
+                        args.get("new_string", ""),
+                        workspace_root,
+                    )
+                elif fn.name == "run_command":
+                    result, _exit_code, _stderr_present = _run_command(
+                        args.get("command", ""),
+                        workspace_root,
+                    )
+                else:
+                    result = f"Error: unknown tool '{fn.name}'."
+
+                api_messages.append(
+                    {
+                        "role": "tool",
+                        "tool_call_id": tool_call.id,
+                        "content": result,
+                    }
+                )
+        else:
+            # No tool calls — final text reply.
+            reply_text = message.content or ""
+            return {"messages": messages + [AIMessage(content=reply_text)]}
+
+    # Exhausted tool rounds.
+    last_msg = api_messages[-1]
+    reply_text = last_msg.get("content", "(debug agent exceeded tool rounds)")
+    return {"messages": messages + [AIMessage(content=reply_text)]}

backend/agents/teacher_agent.py

@@ -0,0 +1,179 @@
+"""Teacher Agent — saves teaching content and answers user questions.
+
+Concept detection no longer happens here: the shared ``detect_concepts``
+node (see :mod:`backend.agents.concept_detector`) runs once per turn and
+writes ``state["concepts_detected"]``.  This node reads that shared result
+and turns the new concepts into teaching entries on the dashboard.
+
+When the user asks a question in the terminal, the teacher agent answers
+it there directly instead.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from langchain_core.messages import AIMessage, BaseMessage, HumanMessage
+
+from backend.llm.client import resolve_api_key, get_client
+from backend.llm.config import get_model
+
+# Shims for backwards compatibility — the detection engine lives in
+# backend.agents.concept_detector now.  These names were importable from
+# here before the refactor; keep the re-exports until all call sites
+# have moved over.
+from backend.agents.concept_detector import (  # noqa: F401
+    CONCEPT_PATTERNS,
+    DetectedConcept,
+    detect_concepts_from_file,
+    detect_concepts_from_tool_calls,
+    detect_concepts_with_llm,
+)
+
+
+def teacher_agent_node(state: dict[str, Any]) -> dict[str, Any]:
+    """LangGraph node: teach the concepts the shared detect_concepts node found.
+
+    Expects ``state["concepts_detected"]`` — written by the detect_concepts
+    node each turn as a list of dicts with ``name``, ``category``,
+    ``description``, and ``diagram`` keys.
+
+    Expects ``state["concepts"]`` for already-known concepts so we don't
+    re-teach them.
+
+    Saves teaching content to the dashboard (via database) rather than
+    printing it in the terminal.  Only a brief notification is shown
+    in the terminal; the full teaching is available on the dashboard.
+
+    When the user asks a question in the terminal, the teacher agent
+    answers there directly.
+    """
+    from backend.database.concepts import save_teaching
+
+    messages: list[BaseMessage] = state.get("messages", [])
+    concepts: list[dict[str, Any]] = state.get("concepts", [])
+    session: str = state.get("session", "default")
+
+    # Check if this is a user question — if so, answer it in the terminal
+    last_user_msg = None
+    for msg in reversed(messages):
+        if isinstance(msg, HumanMessage):
+            last_user_msg = msg
+            break
+
+    if last_user_msg and _is_user_question(last_user_msg.content):
+        # User asked a question — answer it directly in the terminal
+        answer = _answer_user_question(last_user_msg.content, concepts)
+        return {
+            "messages": messages + [AIMessage(content=answer)],
+            "concepts": concepts,
+        }
+
+    # Concepts detected this turn by the shared detect_concepts node.
+    # Already filtered against state["concepts"] during detection, but
+    # keep the known-name guard as defense in depth against duplicates.
+    detected: list[dict[str, Any]] = state.get("concepts_detected", [])
+    known_names: set[str] = {c["name"] for c in concepts}
+
+    new_concepts: list[dict[str, Any]] = []
+    for c in detected:
+        if c["name"] not in known_names:
+            known_names.add(c["name"])
+            new_concepts.append(c)
+
+    if not new_concepts:
+        return {}
+
+    # Save teaching content to the dashboard (not terminal).  The
+    # per-concept Mermaid diagram comes straight from the detection
+    # result — previously the teacher node re-detected concepts itself
+    # and dropped the diagram field, losing the visuals.
+    #
+    # save_teaching deduplicates by concept identity (slug) + code
+    # hash: an unchanged concept re-detected later is a store no-op, so
+    # its explanation and diagram stay consistent even when it
+    # resurfaces in a different file.
+    teaching_entries = []
+    for c in new_concepts:
+        teaching_entry = {
+            "slug": c.get("slug"),
+            "concept_name": c["name"],
+            "concept_category": c["category"],
+            "explanation": c["description"],
+            "decision": c.get("decision", ""),
+            "source_file": c.get("source_file", ""),
+            "diagram": c.get("diagram", ""),
+            "content_hash": c.get("content_hash", ""),
+        }
+        save_teaching(session, teaching_entry)
+        teaching_entries.append(teaching_entry)
+
+    # Brief notification in terminal — full teaching is on the dashboard.
+    # Deliberately lists no concept names here: the terminal stays clean and
+    # the user is pointed to the dashboard for explanations.
+    count = len(new_concepts)
+    teaching_text = (
+        f"📚 {count} new coding concept(s) detected! "
+        f"They're available with explanations on the dashboard "
+        f"(Concepts section)."
+    )
+
+    return {
+        "messages": messages + [AIMessage(content=teaching_text)],
+        "concepts": concepts + new_concepts,
+    }
+
+
+def _is_user_question(text: str) -> bool:
+    """Check if the user's message looks like a question about concepts."""
+    text_lower = text.lower().strip()
+    question_indicators = [
+        "what is", "what are", "what does", "what's",
+        "how does", "how do", "how to", "how can",
+        "why", "when should", "when do", "when to",
+        "can you explain", "tell me about", "describe",
+        "difference between", "vs", "versus",
+        "how does this work", "explain this",
+    ]
+    return any(indicator in text_lower for indicator in question_indicators)
+
+
+def _answer_user_question(question: str, concepts: list[dict[str, Any]]) -> str:
+    """Answer a user's question using the LLM, with concept context."""
+    api_key = resolve_api_key()
+    if not api_key:
+        return "I need an API key to answer questions. Please set GROQ_API_KEY."
+
+    # Build context from known concepts
+    concept_context = ""
+    if concepts:
+        concept_lines = []
+        for c in concepts[-10:]:  # Last 10 concepts for context
+            concept_lines.append(
+                f"- {c['name']} ({c.get('category', 'General')}): "
+                f"{c.get('description', '')}"
+            )
+        concept_context = "\n".join(concept_lines)
+
+    system_prompt = (
+        "You are a helpful coding teacher. Answer the user's question about "
+        "programming concepts. Be clear, concise, and educational. "
+        "Use examples when helpful."
+    )
+
+    if concept_context:
+        system_prompt += f"\n\nRecent concepts in the user's code:\n{concept_context}"
+
+    try:
+        client = get_client()
+        completion = client.chat.completions.create(
+            model=get_model("teaching"),
+            messages=[
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": question},
+            ],
+            max_completion_tokens=1024,
+        )
+        return completion.choices[0].message.content or "I couldn't generate an answer."
+    except Exception as exc:
+        return f"(Error answering question: {exc})"

backend/cli/__init__.py

@@ -0,0 +1 @@
+"""CodeLith command-line interface: interactive CodeLith sessions over the daemon."""

backend/cli/config_cmd.py

@@ -0,0 +1,135 @@
+"""``codelith config`` — inspect and customize model roles.
+
+This command group never starts the daemon and never touches the
+network: ``show``, ``set``, and ``unset`` only read/write
+``~/.codelith/config.toml`` and print current resolution.  It exists
+purely for users who *want* to change models; running plain CodeLith
+never creates the config file.
+
+Usage::
+
+    codelith config                 # show every role + resolved model
+    codelith config show            # same
+    codelith config set <role> <model-slug>
+    codelith config unset <role>    # fall back to env var / default
+
+The exit code is 2 for usage/validation errors so shell scripts can
+distinguish them from plain "nothing to do" output.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from backend.llm import config as llm_config
+from backend.llm.config import MODEL_ROLES, get_model, set_model, unset_model
+
+
+def _print_show() -> None:
+    """Print every role, its override source, and the resolved model."""
+    import os
+
+    path = llm_config.config_path()
+    exists = path.exists()
+    print(f"Config file: {path}" + ("" if exists else " (not created — using built-in defaults)"))
+    print()
+    header = f"{'Role':<12} {'Source':<10} Model"
+    print(header)
+    print("-" * len(header))
+    for role in sorted(MODEL_ROLES):
+        env_name = MODEL_ROLES[role]["env"]
+        if (os.environ.get(env_name) or "").strip():
+            source = f"env:{env_name}"
+        elif exists and get_model(role) != MODEL_ROLES[role]["default"] and not (
+            os.environ.get(env_name) or ""
+        ).strip():
+            # get_model returned something different from the default and
+            # no env var is set, so it must have come from the file.
+            source = "config.toml"
+        else:
+            source = "default"
+        print(f"{role:<12} {source:<10} {get_model(role)}")
+    print()
+    print("Change a model:  codelith config set <role> <provider/model>")
+    print("Reset a role:    codelith config unset <role>")
+    print(f"Valid roles:     {', '.join(sorted(MODEL_ROLES))}")
+
+
+def _cmd_show(_args: argparse.Namespace) -> int:
+    _print_show()
+    return 0
+
+
+def _cmd_set(args: argparse.Namespace) -> int:
+    role, slug = args.role, args.slug
+    if role not in MODEL_ROLES:
+        print(
+            f"Unknown role: {role!r}. Valid roles: {', '.join(sorted(MODEL_ROLES))}",
+            file=sys.stderr,
+        )
+        return 2
+    try:
+        set_model(role, slug)
+    except ValueError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 2
+    print(f"{role} = {slug}")
+    print(f"Saved to {llm_config.config_path()}")
+    return 0
+
+
+def _cmd_unset(args: argparse.Namespace) -> int:
+    role = args.role
+    if role not in MODEL_ROLES:
+        print(
+            f"Unknown role: {role!r}. Valid roles: {', '.join(sorted(MODEL_ROLES))}",
+            file=sys.stderr,
+        )
+        return 2
+    if unset_model(role):
+        print(f"{role} reset (now follows env var / built-in default).")
+    else:
+        print(f"{role} has no override in {llm_config.config_path()}; nothing to unset.")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Return the ``codelith config`` argument parser (with subcommands)."""
+    parser = argparse.ArgumentParser(
+        prog="codelith config",
+        description="Inspect or customize per-role model choices. "
+        "Never starts the daemon; never creates config.toml unless you set a model.",
+    )
+    sub = parser.add_subparsers(dest="config_command")
+
+    sub.add_parser("show", help="show every role and its resolved model")
+
+    p_set = sub.add_parser("set", help="set the model for one role")
+    p_set.add_argument("role", help=f"model role ({', '.join(sorted(MODEL_ROLES))})")
+    p_set.add_argument("slug", help='model slug, e.g. "qwen/qwen3-coder-next" or "openai/gpt-oss-120b"')
+
+    p_unset = sub.add_parser("unset", help="remove a role's override")
+    p_unset.add_argument("role", help="model role to reset")
+
+    # `codelith config` with no subcommand → show.
+    parser.set_defaults(config_command="show", handler=_cmd_show)
+    sub.choices["show"].set_defaults(handler=_cmd_show)  # type: ignore[index]
+    sub.choices["set"].set_defaults(handler=_cmd_set)  # type: ignore[index]
+    sub.choices["unset"].set_defaults(handler=_cmd_unset)  # type: ignore[index]
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for ``codelith config ...``."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    handler = getattr(args, "handler", None)
+    if handler is None:  # pragma: no cover - set_defaults makes this unreachable
+        parser.print_help()
+        return 2
+    return int(handler(args))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())