interview-coach-cli 0.3.0__py3-none-any.whl

coach_graph.py

@@ -0,0 +1,328 @@
+"""
+Coach turn as a LangGraph state machine.
+
+Layout:
+
+    START
+      │
+      ▼
+  classify_turn        (cheap LLM: Haiku / Flash / DeepSeek chat)
+      │
+      ▼
+  match_plan           (no LLM: string overlap against plan.answers_prep)
+      │
+      ▼
+  route                (no LLM: decides which model to use in compose)
+      │
+      ▼
+  compose_reply        (chosen LLM; streams if streaming=True)
+      │
+      ▼
+   END
+
+Design rules:
+  * Fast path: simple/small-talk turns can skip the expensive model.
+  * Any node can fall back to the current `respond()` pipeline on failure.
+  * Streaming is opt-in — CLI turns it on, batch runs (research) keep sync.
+"""
+from __future__ import annotations
+
+import os
+from typing import Optional, TypedDict, Literal
+
+from providers import respond, PROVIDERS
+
+
+TurnType = Literal["question", "statement", "small_talk", "pivot", "instruction"]
+
+
+class TurnState(TypedDict, total=False):
+    # ─── Input (set by caller) ────────────────────────────────────────
+    transcript: str
+    speaker: str                 # "you" | "interviewer" | "unknown"
+    plan: Optional[dict]
+    briefing_present: bool
+    system_prompt: str
+    history: list[dict]
+    provider: str                # default LLM provider
+    model: str                   # default LLM model
+
+    # ─── Intermediate ─────────────────────────────────────────────────
+    turn_type: Optional[TurnType]
+    matched_answer_idx: Optional[int]
+    matched_answer_text: Optional[str]
+    routing_decision: str        # "cheap" | "default" | "premium"
+    routing_reason: str
+
+    # ─── Output ───────────────────────────────────────────────────────
+    reply: str
+    error: Optional[str]
+
+
+# ─── Model tier registry ──────────────────────────────────────────────
+# Given a provider, pick the cheap/default/premium models.
+TIER_MAP = {
+    "anthropic": {
+        "cheap":   "claude-haiku-4-5",
+        "default": "claude-sonnet-4-6",
+        "premium": "claude-opus-4-7",
+    },
+    "openai": {
+        "cheap":   "gpt-5-mini",
+        "default": "gpt-5-mini",
+        "premium": "gpt-5",
+    },
+    "deepseek": {
+        "cheap":   "deepseek-chat",
+        "default": "deepseek-chat",
+        "premium": "deepseek-reasoner",
+    },
+    "gemini": {
+        "cheap":   "gemini-2.5-flash",
+        "default": "gemini-2.5-flash",
+        "premium": "gemini-2.5-pro",
+    },
+}
+
+
+def _tier_model(provider: str, tier: str, fallback: str) -> str:
+    return TIER_MAP.get(provider, {}).get(tier, fallback)
+
+
+# ─── Nodes ────────────────────────────────────────────────────────────
+
+CLASSIFY_SYSTEM = (
+    "You classify a single conversation turn. Output ONE token only, no "
+    "prose, no punctuation. Valid outputs: question | statement | small_talk | "
+    "pivot | instruction. "
+    "\n\n"
+    "Definitions:\n"
+    "  question    = the speaker is asking something that expects an answer\n"
+    "  statement   = the speaker is asserting something (not asking)\n"
+    "  small_talk  = greetings, filler, weather, non-substantive\n"
+    "  pivot       = a section-change signal ('let's move on', 'next topic')\n"
+    "  instruction = the speaker is telling the user what to do\n"
+)
+
+
+SMALL_TALK_MARKERS = {
+    "hello", "hi", "hey", "how are you", "nice to meet",
+    "good morning", "good afternoon", "good evening", "thanks",
+    "thank you", "cheers", "bye", "goodbye", "see you",
+}
+PIVOT_MARKERS = {
+    "let's move on", "next topic", "moving on", "shall we",
+    "next question", "let's talk about", "one more thing",
+}
+
+
+def _fast_classify(transcript: str, speaker: str) -> Optional[TurnType]:
+    """Fast heuristic. Returns None when unsure (fall back to LLM)."""
+    t = transcript.lower().strip()
+    if not t:
+        return "small_talk"
+    words = t.split()
+    n = len(words)
+
+    # Very short utterances are almost always small_talk
+    if n < 4:
+        return "small_talk"
+
+    # Explicit greeting / closing markers
+    for m in SMALL_TALK_MARKERS:
+        if m in t and n < 12:
+            return "small_talk"
+
+    # Pivot signals
+    for m in PIVOT_MARKERS:
+        if m in t:
+            return "pivot"
+
+    # Ends with ? → question
+    if t.endswith("?"):
+        return "question"
+
+    # Speaker heuristics: interviewer utterances are usually questions or
+    # instructions; user utterances are usually statements.
+    if speaker == "interviewer" and n > 6:
+        # Contains a wh-word or "how" → almost certainly a question
+        wh = {"what", "why", "how", "when", "where", "which", "who",
+              "tell me", "walk me", "explain", "describe", "could you", "can you"}
+        for w in wh:
+            if w in t:
+                return "question"
+        return "question"  # default for interviewer
+
+    if speaker == "you" and n > 6:
+        return "statement"
+
+    return None  # let the LLM classifier decide
+
+
+def classify_node(state: TurnState) -> TurnState:
+    """Fast heuristic → LLM classifier only if ambiguous."""
+    transcript = state.get("transcript", "").strip()
+    speaker = state.get("speaker", "unknown")
+
+    fast = _fast_classify(transcript, speaker)
+    if fast is not None:
+        state["turn_type"] = fast
+        return state
+
+    # Ambiguous — call cheap-tier classifier.
+    provider = state["provider"]
+    cheap_model = _tier_model(provider, "cheap", state["model"])
+    try:
+        raw = respond(
+            provider=provider, model=cheap_model,
+            transcript=transcript, history=[],
+            system_prompt=CLASSIFY_SYSTEM,
+        )
+        cleaned = raw.strip().lower().split()[0].strip(".,;:!?")
+        if cleaned in ("question", "statement", "small_talk", "pivot", "instruction"):
+            state["turn_type"] = cleaned  # type: ignore
+        else:
+            state["turn_type"] = "question"
+    except Exception as e:
+        state["error"] = f"classify: {e}"
+        state["turn_type"] = "question"
+    return state
+
+
+def match_plan_node(state: TurnState) -> TurnState:
+    """Try to match the transcript to a prepared answer in the plan. No LLM."""
+    plan = state.get("plan")
+    if not plan:
+        return state
+
+    prep = plan.get("answers_prep") or []
+    if not prep:
+        return state
+
+    transcript_words = {w.lower().strip(".,;:!?") for w in state.get("transcript", "").split()}
+    best_idx = -1
+    best_overlap = 0
+    for i, ans in enumerate(prep):
+        ans_words = {w.lower().strip(".,;:!?") for w in ans.split() if len(w) > 3}
+        overlap = len(transcript_words & ans_words)
+        if overlap > best_overlap:
+            best_overlap = overlap
+            best_idx = i
+    if best_overlap >= 2:  # meaningful overlap (2+ substantive words)
+        state["matched_answer_idx"] = best_idx
+        state["matched_answer_text"] = prep[best_idx]
+    return state
+
+
+def route_node(state: TurnState) -> TurnState:
+    """Decide which model tier to use for the compose step. No LLM."""
+    turn_type = state.get("turn_type") or "question"
+    matched = state.get("matched_answer_text") is not None
+    briefing = state.get("briefing_present", False)
+
+    if turn_type == "small_talk":
+        state["routing_decision"] = "cheap"
+        state["routing_reason"] = "small talk — cheap model is enough"
+    elif turn_type == "pivot":
+        state["routing_decision"] = "cheap"
+        state["routing_reason"] = "pivot — no reasoning needed"
+    elif matched:
+        state["routing_decision"] = "cheap"
+        state["routing_reason"] = "matched a prepared answer — cheap model can compose"
+    elif turn_type == "question" and briefing:
+        state["routing_decision"] = "default"
+        state["routing_reason"] = "question needs briefing-informed answer"
+    elif turn_type == "question":
+        state["routing_decision"] = "default"
+        state["routing_reason"] = "question with no briefing — default is fine"
+    else:
+        state["routing_decision"] = "default"
+        state["routing_reason"] = "default tier"
+    return state
+
+
+def compose_node(state: TurnState) -> TurnState:
+    """Actually compose the SAY/ANALYSIS/WHY response."""
+    provider = state["provider"]
+    default_model = state["model"]
+    tier = state.get("routing_decision", "default")
+    model = _tier_model(provider, tier, default_model)
+
+    # Prepend a note to the transcript so the model knows the turn type +
+    # matched answer if any.
+    prefix_lines = [f"[TURN TYPE: {state.get('turn_type', 'question')}]"]
+    if state.get("matched_answer_text"):
+        prefix_lines.append(
+            f"[MATCHES PREPARED ANSWER #{state['matched_answer_idx']}: "
+            f"{state['matched_answer_text']}]\n"
+            "Use this preparation as the backbone of SAY, but adapt to what "
+            "was actually asked."
+        )
+    prefixed_transcript = "\n".join(prefix_lines) + "\n\n" + state["transcript"]
+
+    try:
+        # We call respond() with a COPY of history so the classifier & match
+        # nodes don't pollute the persistent conversation memory.
+        history_copy = list(state.get("history", []))
+        reply = respond(
+            provider=provider, model=model,
+            transcript=prefixed_transcript, history=history_copy,
+            system_prompt=state["system_prompt"],
+        )
+        state["reply"] = reply
+    except Exception as e:
+        state["reply"] = ""
+        state["error"] = f"compose: {e}"
+    return state
+
+
+# ─── Graph builder ────────────────────────────────────────────────────
+
+def build_graph():
+    from langgraph.graph import StateGraph, START, END
+
+    g = StateGraph(TurnState)
+    g.add_node("classify", classify_node)
+    g.add_node("match_plan", match_plan_node)
+    g.add_node("route", route_node)
+    g.add_node("compose", compose_node)
+
+    g.add_edge(START, "classify")
+    g.add_edge("classify", "match_plan")
+    g.add_edge("match_plan", "route")
+    g.add_edge("route", "compose")
+    g.add_edge("compose", END)
+    return g.compile()
+
+
+# Module-level singleton so we don't rebuild every turn.
+_GRAPH = None
+
+
+def run_turn(
+    transcript: str,
+    speaker: str,
+    system_prompt: str,
+    history: list[dict],
+    provider: str,
+    model: str,
+    plan: Optional[dict] = None,
+    briefing_present: bool = False,
+) -> tuple[str, TurnState]:
+    """Run one turn through the graph. Returns (reply, final_state)."""
+    global _GRAPH
+    if _GRAPH is None:
+        _GRAPH = build_graph()
+
+    initial: TurnState = {
+        "transcript": transcript,
+        "speaker": speaker,
+        "plan": plan,
+        "briefing_present": briefing_present,
+        "system_prompt": system_prompt,
+        "history": history,
+        "provider": provider,
+        "model": model,
+    }
+    final = _GRAPH.invoke(initial)
+    return final.get("reply", ""), final

config.py

@@ -0,0 +1,170 @@
+"""
+Configuration: choose LLM + STT providers, store API keys in .env, remember choice.
+
+Files:
+    .env               — API keys (git-ignored). Loaded on startup.
+    ~/.config/interview-coach/config.json — last-used choices
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from providers import PROVIDERS, key_status
+from transcribers import STT_PROVIDERS, stt_key_status
+
+
+PROJECT_DIR = Path(__file__).parent
+ENV_PATH = PROJECT_DIR / ".env"
+CONFIG_DIR = Path.home() / ".config" / "interview-coach"
+CONFIG_PATH = CONFIG_DIR / "config.json"
+
+
+def load_env():
+    """Load .env into os.environ (does not override existing vars)."""
+    if not ENV_PATH.exists():
+        return
+    for line in ENV_PATH.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        k, v = line.split("=", 1)
+        k, v = k.strip(), v.strip().strip('"').strip("'")
+        os.environ.setdefault(k, v)
+
+
+def load_config() -> dict:
+    if CONFIG_PATH.exists():
+        try:
+            return json.loads(CONFIG_PATH.read_text())
+        except Exception:
+            pass
+    return {}
+
+
+def save_config(cfg: dict):
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CONFIG_PATH.write_text(json.dumps(cfg, indent=2))
+
+
+def _write_env_var(key: str, value: str):
+    """Append or replace a KEY=value line in .env (chmod 600)."""
+    lines = []
+    found = False
+    if ENV_PATH.exists():
+        for line in ENV_PATH.read_text().splitlines():
+            if line.startswith(f"{key}="):
+                lines.append(f"{key}={value}")
+                found = True
+            else:
+                lines.append(line)
+    if not found:
+        lines.append(f"{key}={value}")
+    ENV_PATH.write_text("\n".join(lines) + "\n")
+    os.chmod(ENV_PATH, 0o600)
+    os.environ[key] = value
+
+
+def _pick(kind: str, catalog: dict, current: str | None) -> tuple[str, str]:
+    """Interactive picker for a provider + model. Returns (provider, model)."""
+    keys = list(catalog.keys())
+    print(f"\n  Choose a {kind} provider:\n")
+    for i, p in enumerate(keys, 1):
+        env = catalog[p].get("env")
+        if env is None:
+            state = "✓ no key needed"
+        elif os.environ.get(env):
+            state = "✓ key set"
+        else:
+            state = "  needs key"
+        marker = "  ← current" if p == current else ""
+        print(f"    {i}. {p:<10} [{state}]{marker}")
+
+    while True:
+        raw = input(f"\n  Pick {kind} provider (1-{len(keys)}, Enter to keep current): ").strip()
+        if raw == "" and current:
+            provider = current
+            break
+        if raw.isdigit() and 1 <= int(raw) <= len(keys):
+            provider = keys[int(raw) - 1]
+            break
+        print("  Invalid choice.")
+
+    cfg = catalog[provider]
+    models = list(cfg["models"].keys())
+    print(f"\n  Choose a {provider} model:\n")
+    for i, m in enumerate(models, 1):
+        tag = "  (default)" if m == cfg["default_model"] else ""
+        print(f"    {i}. {m:<26} — {cfg['models'][m]}{tag}")
+
+    while True:
+        raw = input(f"\n  Pick model (1-{len(models)}, Enter for default): ").strip()
+        if raw == "":
+            model = cfg["default_model"]
+            break
+        if raw.isdigit() and 1 <= int(raw) <= len(models):
+            model = models[int(raw) - 1]
+            break
+        print("  Invalid choice.")
+
+    env_var = cfg.get("env")
+    if env_var and not os.environ.get(env_var):
+        print(f"\n  No {env_var} found.")
+        key = input(f"  Paste your {provider} API key (or Enter to skip): ").strip()
+        if key:
+            _write_env_var(env_var, key)
+            print(f"  Saved to {ENV_PATH} (chmod 600).")
+        else:
+            print(f"  Skipped — set {env_var} before running.")
+
+    return provider, model
+
+
+def interactive_setup() -> dict:
+    """First-run wizard: pick LLM + STT provider/model, paste keys if missing."""
+    print("\n" + "─" * 60)
+    print("  CLI Interview Recorder — Setup")
+    print("─" * 60)
+    saved = load_config()
+
+    print("\n" + "=" * 60)
+    print("  STEP 1 of 2 — Language model (answers your interview questions)")
+    print("=" * 60)
+    llm_provider, llm_model = _pick("LLM", PROVIDERS, saved.get("provider"))
+
+    print("\n" + "=" * 60)
+    print("  STEP 2 of 2 — Speech-to-text (transcribes the audio)")
+    print("=" * 60)
+    stt_provider, stt_model = _pick("STT", STT_PROVIDERS, saved.get("stt_provider"))
+
+    choice = {
+        "provider": llm_provider,
+        "model": llm_model,
+        "stt_provider": stt_provider,
+        "stt_model": stt_model,
+    }
+    save_config(choice)
+    print(f"\n  Saved to {CONFIG_PATH}")
+    print("─" * 60 + "\n")
+    return choice
+
+
+def show_status():
+    print("\n  LLM providers:")
+    for provider, has_key in key_status().items():
+        marker = "✓" if has_key else "✗"
+        env = PROVIDERS[provider]["env"]
+        print(f"    {marker} {provider:<10} ({env})")
+
+    print("\n  STT providers:")
+    for provider, has_key in stt_key_status().items():
+        marker = "✓" if has_key else "✗"
+        env = STT_PROVIDERS[provider].get("env") or "no key needed"
+        print(f"    {marker} {provider:<10} ({env})")
+
+    saved = load_config()
+    if saved:
+        print(f"\n  Saved LLM: {saved.get('provider')} / {saved.get('model')}")
+        print(f"  Saved STT: {saved.get('stt_provider', 'local')} / {saved.get('stt_model', 'small')}")
+    print()