From query to wiki: building with the Solver SDK

Authored by Christian Cosgrove, Founding Research Engineer

Diving into unfamiliar codebases is often tedious and time-consuming. Recently, I wondered if I could use the Solver SDK to make this process easier by automatically generating documentation that answers specific questions about a repo.

To do just that, I built a small Flask app powered by the Solver API / SDK. It takes a natural language question about any repository and displays custom Markdown documentation with diagrams and direct links to relevant code.

Solver generates docs on the fly: an example of the app in action

Internally, our Linguist service allows us to determine the language of files within a codebase, among other things. However, the service is complex, and I wanted to get an overview of it before using it.

So, I simply asked Solver through the app:

After submitting this query, the app shows progress:

After the session finishes, the app redirects to a browsable site with relevant diagrams, links, and explanations:

Building with the Solver SDK

The app is built with Python, Flask, and the Solver Python SDK. (More languages coming soon!)

At a high level, here’s how it works:

Step 1: Create a Solver client

We start by initializing the client.

solver_client = Solver(api_key=os.environ["SOLVER_API_KEY"])

Step 2: Start a Solver session

When a user submits a query about a repository, we kick off a Solver session:

instruction_prompt = format_documentation_prompt(query, org, repo)

turn_response = solver_client.repos.sessions.create_and_solve(
    provider="github",
    org=org,
    repo=repo,
    user_branch_name="main",
    instruction=instruction_prompt,
    num_steps=NUM_STEPS
)
# Redirect to the progress page ...

create_and_solve is where the magic happens. First, it creates a session in the requested repository. Then, Solver follows our instructions: analyze the relevant parts of the codebase and generate documentation about the requested topic.

Step 3: Guide Solver

The key to getting good results is a clear prompt.

DOCUMENTATION_PROMPT = """Your goal is to document this project,
with a focus on a particular user query.

You MUST perform the following actions:
- Create a new directory named .wiki/ at the root of this repository.
- Inside the .wiki/ directory, create multiple Markdown (.md) files.
These files should comprehensively document and answer the user's query.
- You must create a table of contents, and that file MUST be named README.md.
This file should list and link to all other Markdown files
you create in the .wiki/ directory.
- ... include Mermaid diagrams within the Markdown files. ...
- ... Include citations that link to the specific lines of code in the repository ...

Remember, the primary output is the .wiki/ directory and its contents,
created directly in the file system.
...
This is the user's query, which is your focus:
<user-query>
$query
</user-query>
"""

Note that we don't just ask Solver to "create some documentation" - we tell it exactly what file structure to create, how to name things, and how to explore the codebase. With the Solver API, you can “program” novel behaviors into the agent simply by changing your prompt.

Step 4: Retrieve the documentation

While this happens, the app shows a progress page to the user. Once Solver finishes (which the app checks by subscribing to status updates for the session), we get the generated Markdown files:

# after confirming session status is "READY":

patch_response = solver_client.repos.sessions.get_patch(
    provider="github",
    org=org,
    repo=repo,
    session_id=session_id
)
patch_content = patch_response.patch_set

Solver returns the Markdown files it created as a patch.

Step 5: Serve the documentation

After getting the patch, we create a new temporary directory and apply the patch to create the files locally:

subprocess.run(["patch", "-p1", "-d", docs_path], input=patch_content, ...)

Then, we use Docsify.js to serve the Markdown files in a clean, browsable format that supports Mermaid diagrams.

Speed and simplicity: the Solver SDK advantage

I built this app in an afternoon, which would have been impossible without the Solver SDK. Think about what it would normally take:

• Setting up GitHub API access 
• Writing many prompts and managing LLM calls
• Creating a secure environment for code execution
• Figuring out how to get the generated files back out
• ... and so much more ...

Even then, there's no guarantee of success. 

Instead, our SDK handles all of the heavy lifting, helping you quickly create tools that would otherwise be complex and time-consuming. If you're building anything that needs to analyze or modify code, try it out or contact us to learn more.