codelith 0.1.0__py3-none-any.whl

backend/llm/__init__.py

@@ -0,0 +1,5 @@
+"""LLM integration for the CodeLith backend (currently Groq)."""
+
+from backend.llm.client import DEFAULT_MODEL, generate_reply
+
+__all__ = ["DEFAULT_MODEL", "generate_reply"]

backend/llm/client.py

@@ -0,0 +1,333 @@
+"""LLM chat clients for the CodeLith daemon.
+
+Two independent providers are used:
+
+- **Groq** — the teaching-side models (teacher agent, assessment grading,
+  concept detection, dashboard questions).  Key: ``GROQ_API_KEY``.
+- **OpenRouter** — the workhorse coding models (coding agent, debug
+  agent).  Key: ``OPENROUTER_API_KEY``.  The model is chosen with
+  ``CODELITH_AGENT_MODEL`` (default: ``qwen/qwen3-coder-next``, a cheap
+  code-specialised model with a 262k context and native tool calling).
+
+Both providers are OpenAI-compatible, so a single ``openai`` SDK client
+is used with a different ``base_url`` per provider.
+
+API keys are resolved from, in order:
+
+1. the environment variable (``GROQ_API_KEY`` / ``OPENROUTER_API_KEY``),
+2. a ``.env`` file in the repository root,
+3. a ``.env`` file in the daemon state directory (``~/.codelith/``).
+
+Files are re-read on every request, so adding a key to a ``.env`` file
+takes effect without restarting the daemon. Usage::
+
+    from backend.llm.client import generate_reply
+
+    reply = generate_reply("What is a closure?")
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Optional
+
+from openai import OpenAI
+
+from backend.llm.config import get_model
+
+GROQ_API_KEY_ENV = "GROQ_API_KEY"
+# Kept for backwards compatibility with existing imports; teaching-side
+# model selection now goes through backend.llm.config.get_model(role).
+DEFAULT_MODEL = "openai/gpt-oss-120b"
+MAX_COMPLETION_TOKENS = 4096
+GROQ_BASE_URL = "https://api.groq.com/openai/v1"
+
+OPENROUTER_API_KEY_ENV = "OPENROUTER_API_KEY"
+OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
+# Coding/debug agent workhorse model.  Qwen3-Coder-Next: code-specialised,
+# native tool calling, 262k context, generous output budget.  Override with
+# the CODELITH_AGENT_MODEL env var, e.g. "anthropic/claude-sonnet-4.5" for
+# the strongest agentic coder (paid) or any OpenRouter "...:free" model.
+DEFAULT_AGENT_MODEL = "qwen/qwen3-coder-next"
+AGENT_MODEL_ENV = "CODELITH_AGENT_MODEL"
+# Per-round completion budget for the coding/debug agents.  OpenRouter
+# models (unlike Groq) expose this via the ``max_tokens`` parameter.
+AGENT_MAX_TOKENS = 8192
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+ENV_FILES = (
+    REPO_ROOT / ".env",
+    Path.home() / ".codelith" / ".env",
+)
+
+# OS credential store (Windows Credential Manager, macOS Keychain,
+# Secret Service).  Keys land here when saved through `codelith setup`;
+# env vars and .env files keep working unchanged for users who prefer
+# them.  keyring is an optional dependency: absence or an unlocked/
+# missing backend degrades gracefully to the .env path below.
+KEYRING_SERVICE = "codelith"
+KEYRING_ACCOUNTS = {
+    GROQ_API_KEY_ENV: "groq",
+    OPENROUTER_API_KEY_ENV: "openrouter",
+}
+
+
+def _keyring_get(env_name: str) -> Optional[str]:
+    """Return a key from the OS credential store, or None.
+
+    Never raises: any keyring failure (module missing, no backend,
+    locked keychain) just means "not stored here" and resolution falls
+    through to the env-var/.env layers.
+    """
+    try:
+        import keyring
+    except ImportError:
+        return None
+    try:
+        secret = keyring.get_password(KEYRING_SERVICE, KEYRING_ACCOUNTS[env_name])
+    except Exception:  # noqa: BLE001 - keyring backends raise many shapes
+        return None
+    return secret.strip() if secret and secret.strip() else None
+
+
+def _keyring_set(env_name: str, api_key: str) -> bool:
+    """Store a key in the OS credential store.  Returns True on success."""
+    try:
+        import keyring
+    except ImportError:
+        return False
+    try:
+        keyring.set_password(KEYRING_SERVICE, KEYRING_ACCOUNTS[env_name], api_key.strip())
+        return True
+    except Exception:  # noqa: BLE001 - no backend / locked store / ACL error
+        return False
+
+
+def store_api_key(provider: str, api_key: str) -> bool:
+    """Securely persist *provider*'s API key (``"groq"``/``"openrouter"``).
+
+    Public entry point for the first-run setup flow.  Returns False when
+    no usable keyring backend exists — the caller should then fall back
+    to advising a .env file instead of storing the key in plaintext.
+    """
+    env_name = {v: k for k, v in KEYRING_ACCOUNTS.items()}.get(provider)
+    if not env_name:
+        raise ValueError(f"unknown provider: {provider!r} (known: {', '.join(sorted(KEYRING_ACCOUNTS.values()))})")
+    if not api_key.strip():
+        raise ValueError("API key must not be empty")
+    return _keyring_set(env_name, api_key)
+
+SYSTEM_PROMPT = (
+    "You are CodeLith, an AI mentor that blends coding assistance with "
+    "adaptive teaching. The user is learning to code. Teach at their level: "
+    "explain concepts clearly, use concrete examples, and guide them toward "
+    "solutions instead of just giving the answer. Keep answers focused and "
+    "conversational, and ask a question now and then to check understanding."
+)
+
+GRADING_SYSTEM_PROMPT = (
+    "You are CodeLith, an AI mentor grading a learner's answer to a concept "
+    "question. Judge whether the answer shows real understanding of the "
+    "concept. Be fair: accept correct answers even if they are worded "
+    "differently from a textbook, but reject answers that are wrong or "
+    "miss the point. Respond ONLY with a JSON object of the form "
+    '{"correct": true or false, "feedback": "..."}. Keep feedback to '
+    "1-2 sentences: if the answer is wrong, name the key idea the learner "
+    "missed without giving the full answer away."
+)
+
+
+def _load_dotenv(path: Path) -> None:
+    """Load ``KEY=VALUE`` pairs from ``path`` without overriding existing vars."""
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return
+    for line in lines:
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#") or "=" not in stripped:
+            continue
+        key, _, value = stripped.partition("=")
+        key = key.strip()
+        value = value.strip().strip('"').strip("'")
+        if key and key not in os.environ:
+            os.environ[key] = value
+
+
+def resolve_api_key() -> Optional[str]:
+    """Return the Groq API key, or None if it is not configured anywhere.
+
+    Resolution order: env var → OS keyring → .env files.  Existing
+    setups (env var or .env) keep working unchanged; the keyring layer
+    is only consulted when those are empty.
+    """
+    if os.environ.get(GROQ_API_KEY_ENV):
+        return os.environ[GROQ_API_KEY_ENV].strip()
+    stored = _keyring_get(GROQ_API_KEY_ENV)
+    if stored:
+        return stored
+    for path in ENV_FILES:
+        _load_dotenv(path)
+        key = os.environ.get(GROQ_API_KEY_ENV)
+        if key:
+            return key.strip()
+    return None
+
+
+def resolve_agent_api_key() -> Optional[str]:
+    """Return the OpenRouter API key, or None if it is not configured anywhere.
+
+    Same resolution order as :func:`resolve_api_key`.
+    """
+    if os.environ.get(OPENROUTER_API_KEY_ENV):
+        return os.environ[OPENROUTER_API_KEY_ENV].strip()
+    stored = _keyring_get(OPENROUTER_API_KEY_ENV)
+    if stored:
+        return stored
+    for path in ENV_FILES:
+        _load_dotenv(path)
+        key = os.environ.get(OPENROUTER_API_KEY_ENV)
+        if key:
+            return key.strip()
+    return None
+
+
+def resolve_agent_model() -> str:
+    """Return the coding-agent model slug (CODELITH_AGENT_MODEL or default)."""
+    return (os.environ.get(AGENT_MODEL_ENV) or DEFAULT_AGENT_MODEL).strip()
+
+
+def get_client() -> OpenAI:
+    """Return an OpenAI-compatible client pointed at Groq."""
+    api_key = resolve_api_key()
+    if not api_key:
+        raise ValueError(
+            "No Groq API key found. Set GROQ_API_KEY "
+            "environment variable, or add it to a .env file."
+        )
+    return OpenAI(
+        base_url=GROQ_BASE_URL,
+        api_key=api_key,
+    )
+
+
+def get_agent_client() -> OpenAI:
+    """Return an OpenAI-compatible client pointed at OpenRouter."""
+    api_key = resolve_agent_api_key()
+    if not api_key:
+        raise ValueError(
+            "No OpenRouter API key found. Set OPENROUTER_API_KEY "
+            "environment variable, or add it to a .env file."
+        )
+    return OpenAI(
+        base_url=OPENROUTER_BASE_URL,
+        api_key=api_key,
+    )
+
+
+def generate_reply(
+    user_message: str,
+    model: Optional[str] = None,
+    history: Optional[list[dict]] = None,
+) -> str:
+    """Ask Groq for a reply to ``user_message`` using the CodeLith persona.
+
+    ``model`` defaults to the resolved *teaching* role model (env var >
+    ``config.toml`` > built-in default) when not given explicitly.
+
+    ``history`` is an optional list of prior turns (``{"role", "content"}``
+    dicts, oldest first) so follow-up questions keep their context.
+
+    Never raises: a missing API key and API/network failures are converted
+    into a readable message so the CLI keeps working without a key.
+    """
+    if model is None:
+        model = get_model("teaching")
+    api_key = resolve_api_key()
+    if not api_key:
+        return (
+            "I need a Groq API key to think. Set the GROQ_API_KEY "
+            "environment variable, or add it to a .env file in the project "
+            "root (see the README), then try again."
+        )
+    try:
+        client = get_client()
+        messages = [{"role": "system", "content": SYSTEM_PROMPT}]
+        for entry in history or []:
+            role = entry.get("role")
+            content = (entry.get("content") or "").strip()
+            if role in ("user", "assistant") and content:
+                messages.append({"role": role, "content": content})
+        messages.append({"role": "user", "content": user_message})
+        completion = client.chat.completions.create(
+            model=model,
+            messages=messages,
+            max_completion_tokens=MAX_COMPLETION_TOKENS,
+        )
+    except Exception as exc:  # noqa: BLE001 - surface any API/network failure
+        return f"(I couldn't reach Groq: {exc})"
+    return completion.choices[0].message.content or ""
+
+
+def grade_answer(
+    question: str,
+    answer: str,
+    concept_name: str,
+    concept_category: str = "",
+    model: Optional[str] = None,
+) -> dict[str, Any]:
+    """Grade a learner's answer to a concept question via the LLM.
+
+    ``model`` defaults to the resolved *grading* role model (env var >
+    ``config.toml`` > built-in default) when not given explicitly.
+
+    Returns ``{"correct": bool, "feedback": str}``.  Never raises: any
+    failure (missing key, API error, unparseable output) is converted into
+    a conservative result — the answer is graded as not-correct with a
+    readable explanation, so a broken grader can never inflate progress.
+    """
+    if model is None:
+        model = get_model("grading")
+    api_key = resolve_api_key()
+    if not api_key:
+        return {
+            "correct": False,
+            "feedback": (
+                "(Grading needs a Groq API key — set GROQ_API_KEY or add it "
+                "to a .env file, then submit again.)"
+            ),
+        }
+
+    category_note = f" (category: {concept_category})" if concept_category else ""
+    user_prompt = (
+        f"Concept: {concept_name}{category_note}\n"
+        f"Question: {question}\n\n"
+        f"Learner's answer: {answer}\n\n"
+        "Grade the answer. Respond ONLY with the JSON object."
+    )
+    try:
+        client = get_client()
+        completion = client.chat.completions.create(
+            model=model,
+            messages=[
+                {"role": "system", "content": GRADING_SYSTEM_PROMPT},
+                {"role": "user", "content": user_prompt},
+            ],
+            max_completion_tokens=512,
+        )
+        raw = (completion.choices[0].message.content or "").strip()
+        # Tolerate code fences or prose around the JSON object.
+        start, end = raw.find("{"), raw.rfind("}")
+        if start == -1 or end <= start:
+            raise ValueError(f"no JSON object in grader output: {raw[:200]}")
+        parsed = json.loads(raw[start : end + 1])
+        correct = bool(parsed.get("correct", False))
+        feedback = str(parsed.get("feedback", "")).strip()
+        return {"correct": correct, "feedback": feedback or ("Correct!" if correct else "Not quite — try again.")}
+    except Exception as exc:  # noqa: BLE001 - conservative failure
+        return {
+            "correct": False,
+            "feedback": f"(Grading failed: {exc}. Your answer was not recorded as correct — please submit again.)",
+        }

backend/llm/config.py

@@ -0,0 +1,254 @@
+"""Model-role resolution for CodeLith.
+
+CodeLith's AI work is split into logical **roles** (coding, debugging,
+teaching, ...).  Each role maps to an LLM model slug; every role
+resolves independently through the same three-layer chain:
+
+1. the role's environment variable (``CODELITH_MODEL_CODING`` ...),
+2. ``~/.codelith/config.toml`` under ``[models]``,
+3. the built-in default for that role.
+
+The first layer that is set wins, so a shell env var can override the
+config file for one command (CI, scripts), while the config file is the
+durable per-machine override.
+
+**No file is ever created automatically.**  A user who never customizes
+models sees zero config behavior: all roles resolve to the built-in
+defaults and nothing appears in ``~/.codelith/``.  ``config.toml`` comes
+into existence only when the user runs ``codelith config set`` (or
+hand-writes the file).
+
+Roles are logical, not physical: nothing stops two roles from using the
+same model, and multiple roles currently share the built-in defaults.
+
+Usage::
+
+    from backend.llm.config import get_model
+
+    model = get_model("grading")
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover - depends on the interpreter running the tests
+    try:
+        import tomli as tomllib  # type: ignore[no-redef]
+    except ImportError:  # pragma: no cover - degraded mode, see below
+        tomllib = None  # type: ignore[assignment]
+
+from backend.daemon.state import state_dir
+
+# ---------------------------------------------------------------------------
+# Role registry
+# ---------------------------------------------------------------------------
+
+#: Every logical model role, with its built-in default and env-var name.
+#: Defaults are the models CodeLith ships with today; a role with no
+#: override resolves to exactly what it used before this module existed.
+MODEL_ROLES: dict[str, dict[str, str]] = {
+    "coding": {
+        "default": "qwen/qwen3-coder-next",
+        "env": "CODELITH_MODEL_CODING",
+    },
+    "debugging": {
+        "default": "qwen/qwen3-coder-next",
+        "env": "CODELITH_MODEL_DEBUGGING",
+    },
+    "teaching": {
+        "default": "openai/gpt-oss-120b",
+        "env": "CODELITH_MODEL_TEACHING",
+    },
+    "assessment": {
+        "default": "openai/gpt-oss-120b",
+        "env": "CODELITH_MODEL_ASSESSMENT",
+    },
+    "grading": {
+        "default": "openai/gpt-oss-120b",
+        "env": "CODELITH_MODEL_GRADING",
+    },
+    "detection": {
+        "default": "openai/gpt-oss-120b",
+        "env": "CODELITH_MODEL_DETECTION",
+    },
+}
+
+CONFIG_FILE_NAME = "config.toml"
+
+# mtime cache: the TOML file is parsed at most once per modification.
+# Keeps the "edit the file, no daemon restart" behavior of the .env
+# loader while avoiding a disk hit + reparse on every LLM call.
+_cache: dict[str, object] = {"mtime": None, "models": {}}
+
+
+def config_path() -> Path:
+    """Return the config file path (``~/.codelith/config.toml``)."""
+    return state_dir() / CONFIG_FILE_NAME
+
+
+def _parse_toml(text: str) -> dict:
+    """Parse *text* as TOML, or return {} when no parser is available."""
+    if tomllib is None:  # pragma: no cover - Python < 3.11 without tomli
+        return {}
+    return tomllib.loads(text)
+
+
+def _read_models_table(path: Path) -> dict[str, str]:
+    """Return the ``[models]`` table from *path* as ``role -> slug``.
+
+    Returns {} when the file is missing, unreadable, unparsable, or has
+    no ``[models]`` table — a broken config file degrades to built-in
+    defaults rather than breaking every LLM call.
+    """
+    try:
+        data = _parse_toml(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):  # missing file / TOML syntax error
+        return {}
+    models = data.get("models")
+    if not isinstance(models, dict):
+        return {}
+    return {
+        str(role): str(slug).strip()
+        for role, slug in models.items()
+        if str(slug).strip()
+    }
+
+
+def _file_models() -> dict[str, str]:
+    """Return the parsed ``[models]`` table, re-reading only when the file changed."""
+    path = config_path()
+    try:
+        mtime = path.stat().st_mtime_ns
+    except OSError:
+        # No file (the common case) — reset the cache so a file created
+        # later is picked up instead of being shadowed by a stale table.
+        _cache["mtime"] = None
+        _cache["models"] = {}
+        return {}
+    if _cache["mtime"] != mtime:
+        _cache["models"] = _read_models_table(path)
+        _cache["mtime"] = mtime
+    models: dict[str, str] = _cache["models"]  # type: ignore[assignment]
+    return models
+
+
+def get_model(role: str) -> str:
+    """Return the model slug for *role*.
+
+    Resolution order: role env var → ``config.toml`` ``[models]`` →
+    built-in default.  Unknown roles raise ``KeyError`` — a typo'd role
+    is a programming error, not a runtime condition.
+    """
+    entry = MODEL_ROLES.get(role)
+    if entry is None:
+        raise KeyError(f"unknown model role: {role!r} (known: {', '.join(sorted(MODEL_ROLES))})")
+
+    env_value = (os.environ.get(entry["env"]) or "").strip()
+    if env_value:
+        return env_value
+
+    file_value = _file_models().get(role, "").strip()
+    if file_value:
+        return file_value
+
+    return entry["default"]
+
+
+# ---------------------------------------------------------------------------
+# Explicit writes — the only way config.toml comes into existence
+# ---------------------------------------------------------------------------
+
+
+def set_model(role: str, slug: str) -> None:
+    """Persist *role* → *slug* in ``config.toml``, creating the file.
+
+    Preserves any other TOML content conservatively: when the existing
+    file parses, the ``[models]`` table is updated in place and the rest
+    of the document is re-emitted unchanged.  When it does not parse,
+    the write is refused rather than destroying the user's file.
+
+    Unknown roles are rejected — ``codelith config set`` is the only
+    writer, and it validates against :data:`MODEL_ROLES` first.
+    """
+    if role not in MODEL_ROLES:
+        raise KeyError(f"unknown model role: {role!r} (known: {', '.join(sorted(MODEL_ROLES))})")
+    slug = slug.strip()
+    if not slug:
+        raise ValueError("model slug must not be empty")
+
+    path = config_path()
+    existing_text = ""
+    try:
+        existing_text = path.read_text(encoding="utf-8")
+    except OSError:
+        pass  # new file
+
+    if existing_text.strip():
+        try:
+            data = _parse_toml(existing_text)
+        except ValueError as exc:
+            raise ValueError(
+                f"{path} is not valid TOML ({exc}); fix or remove it before running "
+                "`codelith config set`."
+            ) from exc
+        data.setdefault("models", {})
+        data["models"][role] = slug
+        body = _dump_toml(data)
+    else:
+        body = _dump_toml({"models": {role: slug}})
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(body, encoding="utf-8")
+    _cache["mtime"] = None  # force re-read on next resolve
+
+
+def unset_model(role: str) -> bool:
+    """Remove *role* from ``config.toml``.  Returns True if it was present.
+
+    The file itself is kept (other settings may live there); an empty
+    ``[models]`` table is left behind rather than deleting the file,
+    which keeps hand-edited comments and unrelated sections intact.
+    """
+    if role not in MODEL_ROLES:
+        raise KeyError(f"unknown model role: {role!r} (known: {', '.join(sorted(MODEL_ROLES))})")
+
+    path = config_path()
+    try:
+        data = _parse_toml(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return False
+
+    models = data.get("models")
+    if not isinstance(models, dict) or role not in models:
+        return False
+
+    del models[role]
+    path.write_text(_dump_toml(data), encoding="utf-8")
+    _cache["mtime"] = None
+    return True
+
+
+def _dump_toml(data: dict) -> str:
+    """Serialize *data* to a readable TOML string (tables one key deep)."""
+    lines: list[str] = []
+    for key, value in data.items():
+        if isinstance(value, dict):
+            lines.append(f"[{key}]")
+            for sub_key, sub_value in value.items():
+                lines.append(f"{sub_key} = {_toml_string(str(sub_value))}")
+            lines.append("")
+        else:
+            lines.append(f"{key} = {_toml_string(str(value))}")
+            lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _toml_string(value: str) -> str:
+    """Quote *value* as a basic TOML string."""
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'