Skip to content

A curated collection of practical AI projects implementing OCR systems, RAG, AI agents, and other AI use cases.

5.0 KB
Raw Blame
"""LangGraph workflow that plans a targeted, read-only repository investigation."""

from __future__ import annotations

from langgraph.graph import END, START, StateGraph

from codebase_guide.llm import LLMError, chat, json_object
from codebase_guide.models import GuideAnswer, GuideState, RepositorySnapshot, SourceFile
from codebase_guide.repository import rank_paths


def _tree_preview(paths: list[str]) -> str:
    return "\n".join(f"- {path}" for path in paths[:900])


def _numbered(file: SourceFile) -> str:
    lines = file.content.splitlines()
    trimmed = lines[:500]
    return "\n".join(f"{index + 1}: {line}" for index, line in enumerate(trimmed))


def _select_paths(question: str, snapshot: RepositorySnapshot) -> tuple[str, list[str]]:
    prompt = f"""You are planning a read-only investigation of a software repository.
Question: {question}
Repository: {snapshot.name}
Description: {snapshot.description}
Default branch: {snapshot.default_branch}
Available files:\n{_tree_preview(snapshot.file_paths)}

Return JSON only: {{"plan": "one sentence", "paths": ["path/to/file"]}}.
Choose at most 6 paths. Every selected path must appear exactly in Available files.
Start with manifests, entry points, routes, or tests only when relevant to the question."""
    try:
        data = json_object(chat([{"role": "user", "content": prompt}]))
        proposed = [str(item) for item in data.get("paths", [])]
        selected = [path for path in proposed if path in snapshot.file_paths][:6]
        if selected:
            return str(data.get("plan", "Inspecting the files most relevant to the question.")), selected
    except LLMError:
        pass
    return "Using a deterministic file selection because model planning was unavailable.", rank_paths(
        snapshot.file_paths, question
    )


def _write_answer(question: str, snapshot: RepositorySnapshot, files: list[SourceFile]) -> str:
    evidence = "\n\n".join(f"FILE: {file.path}\n{_numbered(file)}" for file in files)
    prompt = f"""You are a careful codebase onboarding guide. Answer this question about the repository:
{question}

Repository: {snapshot.name}
Description: {snapshot.description}

Use only the supplied source files. Do not infer behaviour from a filename alone. If the evidence does not answer the question, say what is unknown.
Write a concise answer for a developer. Every factual statement about implementation needs one or more inline citations in exactly this format: [path:line]. Cite only a supplied file and valid line number.

SOURCE FILES:
{evidence}"""
    return chat([{"role": "user", "content": prompt}], temperature=0.15)


def _write_spoken_brief(question: str, answer: str) -> str:
    prompt = f"""Turn this codebase answer into a natural spoken response for a developer.

Question: {question}
Written answer: {answer}

Rules:
- Use only facts stated in the written answer. Do not add information.
- Answer the question directly in two to four short sentences, under 90 words.
- Keep the important language, framework, or architecture conclusion when relevant.
- Do not read citations, Markdown, headings, bullet points, URLs, file paths, line numbers, code, or a complete list of dependencies.
- Use normal spoken English. For example, say “The project is mainly written in Python” rather than reciting file extensions.
- Return only the words to be spoken."""
    return chat([{"role": "user", "content": prompt}], temperature=0.2)


def build_graph(reader):
    def plan(state: GuideState) -> GuideState:
        plan_text, paths = _select_paths(state["question"], state["snapshot"])
        return {"plan": plan_text, "selected_paths": paths}

    def collect(state: GuideState) -> GuideState:
        snapshot = state["snapshot"]
        files = reader.read_files(state["selected_paths"], snapshot.default_branch)
        return {"files": files}

    def answer(state: GuideState) -> GuideState:
        files = state["files"]
        if not files:
            return {"answer": "I could not read the selected files. Try another repository or a more specific question."}
        return {"answer": _write_answer(state["question"], state["snapshot"], files)}

    graph = StateGraph(GuideState)
    graph.add_node("plan", plan)
    graph.add_node("collect", collect)
    graph.add_node("answer", answer)
    graph.add_edge(START, "plan")
    graph.add_edge("plan", "collect")
    graph.add_edge("collect", "answer")
    graph.add_edge("answer", END)
    return graph.compile()


def investigate(reader, snapshot: RepositorySnapshot, question: str) -> GuideAnswer:
    result = build_graph(reader).invoke({"question": question, "snapshot": snapshot})
    answer = result["answer"]
    try:
        spoken_answer = _write_spoken_brief(question, answer)
    except LLMError:
        spoken_answer = answer
    return GuideAnswer(
        question=question,
        answer=answer,
        spoken_answer=spoken_answer,
        files=result.get("files", []),
        selected_paths=result.get("selected_paths", []),
        plan=result.get("plan", ""),
    )