explainthisrepo 0.6.1 → 0.9.0

package/README.md

@@ -1,6 +1,8 @@
 # ExplainThisRepo
 
-ExplainThisRepo is a CLI that generates plain-English explanations of any codebase (GitHub repositories and local directories) by analyzing project structure, README content, and high signal files.
+ExplainThisRepo is a CLI that generates plain-English explanations of any codebase (GitHub repositories and local directories) by analyzing project structure, READMEs, and high signal files.
+
+ExplainThisRepo is a command-line tool that analyzes GitHub repositories and local directories to generate plain-English explanations of the codebase architecture.
 
 It helps developers quickly understand unfamiliar codebases by deriving architectural explanations from real project structure and code signals, producing a clear, structured `EXPLAIN.md`.
 
@@ -26,9 +28,9 @@ It helps developers quickly understand unfamiliar codebases by deriving architec
 - Builds a file tree summary to understand project architecture
 - Detects programming languages with the GitHub API
 - Analyzes local project directories using the same pipeline as GitHub repositories
-- Generates a structured plain English explanation grounded in actual project files
-- Outputs the explanation to an `EXPLAIN.md` file in your current directory or print it directly in the terminal
-- Multi mode command-line interface
+- Generates a structured plain-English explanation grounded in actual project files
+- Outputs the explanation to an `EXPLAIN.md` file in your current directory or prints it directly in the terminal
+- Multi-mode command-line interface
 
 ---
 
@@ -48,29 +50,27 @@ It helps developers quickly understand unfamiliar codebases by deriving architec
 
 - `--help` → Show usage guide
 
-- `--doctor` → Check environmental health and API connectivity
+- `--doctor` → Check system health and active model diagnostics
 
 ---
 
 ## Configuration
 
-ExplainThisRepo uses Gemini models for code analysis.
-
-Set your Google Gemini API key as an environment variable.
+ExplainThisRepo supports multiple LLM models:
 
-Linux / macOS
+- Gemini
+- OpenAI
+- Ollama (local or cloud-routed)
 
-```bash
-export GEMINI_API_KEY="your_api_key_here"
-```
+### Quick setup (recommended)
 
-Windows (PowerShell)
+Use the built-in `init` command to configure your preferred model:
 
 ```bash
-setx GEMINI_API_KEY "your_api_key_here"
+explainthisrepo init
+# or npx explainthisrepo init
 ```
-
-Restart your terminal after setting the key.
+> For details about how initialization works, see [INIT.md](INIT.md).
 
 ## Installation
 
@@ -90,6 +90,13 @@ pipx install explainthisrepo
 explainthisrepo owner/repo
 ```
 
+To install support for specific models:
+
+```bash
+pip install explainthisrepo[gemini]
+pip install explainthisrepo[openai]
+```
+
 ### Option 2: Install with npm
 
 Install globally and use forever:
@@ -121,6 +128,18 @@ All inputs are normalized internally to `owner/repo`.
 
 ---
 
+## Model selection
+
+The `--llm` flag to selects which configured model backend to use for the current command
+
+```bash
+explainthisrepo owner/repo --llm gemini
+explainthisrepo owner/repo --llm openai
+explainthisrepo owner/repo --llm ollama
+```
+
+`--llm` works with all modes (``--quick``, ``--simple``, ``--detailed``).
+
 ## Usage
 
 ### Basic
@@ -183,7 +202,7 @@ explainthisrepo owner/repo --stack
 ```
 ![Stack detector Output](assets/stack-command-output.png)
 
-### Local Directory Analysis
+## Local Directory Analysis
 
 ExplainThisRepo can analyze local directories directly in the terminal, using the same modes and output formats as GitHub repositories
 
@@ -203,7 +222,7 @@ explainthisrepo . --stack
 
 When analyzing a local directory:
 - Repository structure is derived from the filesystem
-- Key files (README, configs, entrypoints) are extracted locally
+- High signal files (Configs, README, entrypoints) are extracted locally
 - No GitHub APIs calls are made
 - All prompts and outputs remain identical
 
@@ -219,15 +238,22 @@ explainthisrepo --version
 
 ---
 
-### Doctor
-
-Check environment and connectivity (useful for debugging):
+### Diagnostics
+Use the `--doctor` flag to verify the environment, network connectivity, and API key configuration:
 
 ```bash
 explainthisrepo --doctor
 ```
 
-### Termux (Android) install notes
+### Set GitHub Token
+
+Setting a `GITHUB_TOKEN` environment variable is recommended to avoid rate limits when analyzing public repositories.
+
+```bash
+export GITHUB_TOKEN=yourActualTokenHere
+```
+
+## Termux (Android) install notes
 
 Termux has some environment limitations that can make `pip install explainthisrepo` fail to create the `explainthisrepo` command in `$PREFIX/bin`.
 
@@ -238,12 +264,14 @@ pip install --user -U explainthisrepo
 ```
 
 Make sure your user bin directory is on your PATH:
+
 ```bash
 export PATH="$HOME/.local/bin:$PATH"
 ```
+
 > Tip: Add the PATH export to your ~/.bashrc or ~/.zshrc so it persists.
 
-Alternative (No PATH changes)
+### Alternative (No PATH changes)
 
 If you do not want to modify PATH, you can run ExplainThisRepo as a module:
 
@@ -251,7 +279,7 @@ If you do not want to modify PATH, you can run ExplainThisRepo as a module:
 python -m explain_this_repo owner/repo
 ```
 
-### Gemini support on Termux (Optional)
+### Gemini support on Termux
 
 Installing Gemini support may require building Rust-based dependencies on Android, which can take time on first install:
 
@@ -281,5 +309,5 @@ This project is licensed under the MIT License. See the [LICENSE](LICENSE) file
 Caleb Wodi
 
 - Email: caleb@explainthisrepo.com
-- Twitter: [@calchiwo](https://x.com/calchiwo)
-- LinkedIn: [@calchiwo](https://linkedin.com/in/calchiwo)
+- LinkedIn: [@calchiwo](https://linkedin.com/in/calchiwo)
+- Twitter: [@calchiwo](https://x.com/calchiwo)

package/dist/cli.js

@@ -64,9 +64,6 @@ function getPkgVersion() {
         return "unknown";
     }
 }
-function printVersion() {
-    console.log(getPkgVersion());
-}
 function hasEnv(key) {
     const v = process.env[key];
     return Boolean(v && v.trim());
@@ -90,21 +87,63 @@ async function checkUrl(url, timeoutMs = 6000) {
         return { ok: false, msg: `failed (${name}: ${message})` };
     }
 }
-async function runDoctor() {
+async function runDoctor(llmOverride) {
     console.log("explainthisrepo doctor report\n");
     console.log(`node: ${process.version}`);
     console.log(`os: ${os.type()} ${os.release()}`);
     console.log(`platform: ${process.platform} ${process.arch}`);
     console.log(`version: ${getPkgVersion()}`);
     console.log("\nenvironment:");
-    console.log(`- GEMINI_API_KEY set: ${hasEnv("GEMINI_API_KEY")}`);
     console.log(`- GITHUB_TOKEN set: ${hasEnv("GITHUB_TOKEN")}`);
     console.log("\nnetwork checks:");
     const gh = await checkUrl("https://api.github.com");
     console.log(`- github api: ${gh.msg}`);
-    const gem = await checkUrl("https://generativelanguage.googleapis.com");
-    console.log(`- gemini endpoint: ${gem.msg}`);
-    return gh.ok && gem.ok ? 0 : 1;
+    console.log("\nprovider diagnostics:");
+    let providerOk = true;
+    try {
+        const { getActiveProvider } = await import("./providers/registry.js");
+        const provider = await getActiveProvider(llmOverride);
+        const providerName = provider.name ?? llmOverride ?? "unknown";
+        console.log(`- active provider: ${providerName}`);
+        const doctorFn = provider.doctor;
+        if (typeof doctorFn === "function") {
+            const result = await doctorFn.call(provider);
+            if (typeof result === "boolean") {
+                console.log(`- ${providerName}: ${result ? "ok" : "checks did not pass"}`);
+                providerOk = result;
+            }
+            else if (Array.isArray(result)) {
+                if (result.length === 0) {
+                    console.log(`- ${providerName}: ok`);
+                }
+                else {
+                    for (const line of result) {
+                        console.log(`- ${providerName}: ${line}`);
+                    }
+                    providerOk = false;
+                }
+            }
+            else {
+                console.log(`- ${providerName}: ok`);
+            }
+        }
+        else {
+            console.log(`- ${providerName}: no diagnostics implemented`);
+        }
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        if (llmOverride) {
+            console.log(`- provider '${llmOverride}' could not be resolved`);
+            console.log("- check that the provider name is correct and properly configured");
+        }
+        else {
+            console.log(`- provider registry error: ${message}`);
+            console.log("- run `explainthisrepo init` to configure a provider");
+        }
+        providerOk = false;
+    }
+    return gh.ok && providerOk ? 0 : 1;
 }
 async function safeReadRepoFiles(owner, repo) {
     try {
@@ -116,60 +155,24 @@ async function safeReadRepoFiles(owner, repo) {
         return null;
     }
 }
-async function generateWithExit(prompt) {
+async function generateWithExit(prompt, llm) {
     try {
-        return await generateExplanation(prompt);
+        return await generateExplanation(prompt, llm);
     }
     catch (e) {
         const message = e instanceof Error ? e.message : String(e);
         console.error("Failed to generate explanation.");
         console.error(`error: ${message}`);
         console.error("\nfix:");
-        console.error("- Ensure GEMINI_API_KEY is set");
+        console.error("- Check that the provider name is correct (e.g. gemini, openai, ollama)");
+        console.error("- Ensure your API key is set for the selected provider");
         console.error("- Or run: explainthisrepo --doctor");
         process.exit(1);
     }
 }
-async function main() {
-    const program = new Command();
-    program
-        .name("explainthisrepo")
-        .description("CLI that generates plain English explanations of any codebase")
-        .version(getPkgVersion(), "-v, --version", "Show version")
-        .argument("[repository]", "GitHub repository (owner/repo or URL) or local directories")
-        .option("--doctor", "Run diagnostics")
-        .option("--quick", "Quick summary mode")
-        .option("--simple", "Simple summary mode")
-        .option("--detailed", "Detailed explanation mode")
-        .option("--stack", "Stack detection mode")
-        .addHelpText("after", `
-Examples:
-  $ explainthisrepo owner/repo
-  $ explainthisrepo https://github.com/owner/repo
-  $ explainthisrepo github.com/owner/repo
-  $ explainthisrepo git@github.com:owner/repo.git
-  $ explainthisrepo owner/repo --detailed
-  $ explainthisrepo owner/repo --quick
-  $ explainthisrepo owner/repo --simple
-  $ explainthisrepo owner/repo --stack
-  $ explainthisrepo .
-  $ explainthisrepo ./path/to/directory
-  $ explainthisrepo . --stack
-  $ explainthisrepo --doctor`);
-    program
-        .command("init")
-        .description("Initialize configuration with Gemini API key")
-        .action(async () => {
-        await runInit();
-    });
-    program.parse(process.argv);
-    if (process.argv[2] === "init") {
-        return;
-    }
-    const options = program.opts();
-    const repository = program.args[0];
+async function runAnalysis(repository, options) {
     if (options.doctor) {
-        const code = await runDoctor();
+        const code = await runDoctor(options.llm);
         process.exit(code);
     }
     const modeFlags = [
@@ -182,9 +185,6 @@ Examples:
         console.error("error: only one mode flag can be used at a time");
         process.exit(1);
     }
-    if (!repository) {
-        program.error("repository argument required (or use `init` to set up API key)");
-    }
     const local = fs.existsSync(repository);
     let owner = "";
     let repo = "";
@@ -266,7 +266,9 @@ Examples:
     if (options.quick) {
         let quickReadme = readme;
         const repoName = local ? localPath : (repoData?.full_name ?? "");
-        const description = local ? null : (repoData?.description ?? null);
+        const description = local
+            ? null
+            : (repoData?.description ?? null);
         if (local) {
             const spinner = ora("Reading repository files…").start();
             try {
@@ -282,7 +284,7 @@ Examples:
         }
         const prompt = buildQuickPrompt(repoName, description, quickReadme);
         const spinner = ora("Generating explanation…").start();
-        const output = await generateWithExit(prompt).finally(() => spinner.stop());
+        const output = await generateWithExit(prompt, options.llm).finally(() => spinner.stop());
         console.log("Quick summary 🎉");
         console.log(output.trim());
         return;
@@ -302,7 +304,7 @@ Examples:
         }
         const prompt = buildSimplePrompt(local ? localPath : (repoData?.full_name ?? ""), local ? null : (repoData?.description ?? null), local ? null : readme, readResult?.treeText ?? null);
         const genSpinner = ora("Generating explanation…").start();
-        const output = await generateWithExit(prompt).finally(() => genSpinner.stop());
+        const output = await generateWithExit(prompt, options.llm).finally(() => genSpinner.stop());
         console.log("Simple summary 🎉");
         console.log(output.trim());
         return;
@@ -321,7 +323,7 @@ Examples:
     }
     const prompt = buildPrompt(local ? localPath : (repoData?.full_name ?? ""), local ? null : (repoData?.description ?? null), local ? null : readme, options.detailed || false, readResult?.treeText ?? null, readResult?.filesText ?? null);
     const genSpinner = ora("Generating explanation…").start();
-    const output = await generateWithExit(prompt).finally(() => genSpinner.stop());
+    const output = await generateWithExit(prompt, options.llm).finally(() => genSpinner.stop());
     console.log("Writing EXPLAIN.md...");
     writeOutput(output);
     const wordCount = output.split(/\s+/).filter(Boolean).length;
@@ -329,4 +331,53 @@ Examples:
     console.log(`Words: ${wordCount}`);
     console.log("Open EXPLAIN.md to read it.");
 }
-main();
+const program = new Command();
+program
+    .name("explainthisrepo")
+    .description("CLI that generates plain English explanations of any codebase")
+    .version(getPkgVersion(), "-v, --version", "Show version")
+    .argument("[repository]", "GitHub repository (owner/repo or URL) or local directories")
+    .option("--doctor", "Run diagnostics")
+    .option("--quick", "Quick summary mode")
+    .option("--simple", "Simple summary mode")
+    .option("--detailed", "Detailed explanation mode")
+    .option("--stack", "Stack detection mode")
+    .option("--llm <provider>", "LLM provider to use (e.g. gemini, openai, ollama). Overrides config default.")
+    .addHelpText("after", `
+Examples:
+  $ explainthisrepo owner/repo
+  $ explainthisrepo https://github.com/owner/repo
+  $ explainthisrepo github.com/owner/repo
+  $ explainthisrepo git@github.com:owner/repo.git
+  $ explainthisrepo owner/repo --detailed
+  $ explainthisrepo owner/repo --quick
+  $ explainthisrepo owner/repo --simple
+  $ explainthisrepo owner/repo --stack
+  $ explainthisrepo owner/repo --llm gemini
+  $ explainthisrepo owner/repo --llm openai
+  $ explainthisrepo owner/repo --llm ollama
+  $ explainthisrepo .
+  $ explainthisrepo ./path/to/directory
+  $ explainthisrepo . --stack
+  $ explainthisrepo --doctor
+  $ explainthisrepo --doctor --llm gemini
+  $ explainthisrepo --doctor --llm openai
+  $ explainthisrepo --doctor --llm ollama`)
+    .action(async (repository, options) => {
+    if (options.doctor) {
+        const code = await runDoctor(options.llm);
+        process.exit(code);
+    }
+    if (!repository) {
+        program.error("repository argument required (or use `explainthisrepo init` to configure a provider)");
+        return;
+    }
+    await runAnalysis(repository, options);
+});
+program
+    .command("init")
+    .description("Configure your LLM provider (Gemini, OpenAI, or Ollama)")
+    .action(async () => {
+    await runInit();
+});
+program.parseAsync(process.argv);

package/dist/config.d.ts

@@ -2,3 +2,4 @@ export declare function getConfigPath(): string;
 export declare function ensureConfigDir(): string;
 export declare function writeConfig(contents: string): void;
 export declare function readConfig(): string | null;
+export declare function loadConfig(): any;

package/dist/config.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import toml from "toml";
 const CONFIG_DIR_NAME = "ExplainThisRepo";
 const CONFIG_FILE_NAME = "config.toml";
 export function getConfigPath() {
@@ -31,3 +32,15 @@ export function readConfig() {
         return null;
     return fs.readFileSync(path, "utf-8");
 }
+export function loadConfig() {
+    const raw = readConfig();
+    if (!raw) {
+        return {};
+    }
+    try {
+        return toml.parse(raw);
+    }
+    catch (err) {
+        throw new Error("Invalid config.toml format");
+    }
+}

package/dist/generate.d.ts

@@ -1 +1 @@
-export declare function generateExplanation(prompt: string): Promise<string>;
+export declare function generateExplanation(prompt: string, providerOverride?: string): Promise<string>;

package/dist/generate.js

@@ -1,36 +1,15 @@
-import { GoogleGenerativeAI } from "@google/generative-ai";
-const DEFAULT_MODEL = "gemini-2.5-flash-lite";
-function getApiKey() {
-    const key = process.env.GEMINI_API_KEY;
-    if (!key || !key.trim()) {
-        throw new Error([
-            "GEMINI_API_KEY is not set.",
-            "",
-            "Fix:",
-            '  export GEMINI_API_KEY="your_key_here"',
-        ].join("\n"));
-    }
-    return key.trim();
-}
-export async function generateExplanation(prompt) {
-    const apiKey = getApiKey();
-    const genAI = new GoogleGenerativeAI(apiKey);
-    const modelName = (process.env.GEMINI_MODEL || DEFAULT_MODEL).trim();
-    const model = genAI.getGenerativeModel({ model: modelName });
+import { getActiveProvider } from "./providers/registry.js";
+export async function generateExplanation(prompt, providerOverride) {
+    const provider = getActiveProvider(providerOverride);
     try {
-        const result = await model.generateContent(prompt);
-        const text = result?.response?.text?.() ?? "";
-        if (!text.trim()) {
-            throw new Error("Gemini returned no text");
+        const output = await provider.generate(prompt);
+        if (!output || !output.trim()) {
+            throw new Error(`${provider.name} returned no output`);
         }
-        return text.trim();
+        return output.trim();
     }
     catch (err) {
-        const msg = err?.message ? String(err.message) : String(err);
-        throw new Error([
-            "Failed to generate explanation (Gemini).",
-            `Model: ${modelName}`,
-            `Error: ${msg}`,
-        ].join("\n"));
+        const message = err?.message ? String(err.message) : String(err);
+        throw new Error(`${provider.name} generation failed: ${message}`);
     }
 }

package/dist/init.js

@@ -2,29 +2,94 @@ import readline from "node:readline";
 import process from "node:process";
 import chalk from "chalk";
 import { writeConfig } from "./config.js";
-const CONFIG_TEMPLATE = `[llm]
-provider = "gemini"
-api_key = "{api_key}"
-`;
+const PROVIDERS = {
+    "1": "gemini",
+    "2": "openai",
+    "3": "ollama"
+};
 export async function runInit() {
     const err = process.stderr;
-    err.write(chalk.yellow("WARNING: input is hidden. Paste your GEMINI_API_KEY and press Enter.\n\n"));
+    err.write(chalk.yellow("WARNING: input is hidden where applicable. Configuration will be written once.\n\n"));
     try {
-        const apiKey = (await promptHidden("Gemini API key: ")).trim();
-        if (!apiKey) {
-            err.write(chalk.red("error: API key cannot be empty\n"));
-            process.exit(1);
+        const provider = await promptProvider();
+        const providerConfig = await promptProviderConfig(provider);
+        const lines = [
+            "[llm]",
+            `provider = "${provider}"`,
+            "",
+            `[providers.${provider}]`
+        ];
+        for (const [k, v] of Object.entries(providerConfig)) {
+            lines.push(`${k} = "${v}"`);
         }
-        writeConfig(CONFIG_TEMPLATE.replace("{api_key}", apiKey));
-        err.write("\r");
-        err.write("\x1b[2K");
+        const contents = lines.join("\n") + "\n";
+        writeConfig(contents);
         err.write(chalk.green("Configuration written.\n"));
         process.exit(0);
     }
-    catch {
-        err.write(chalk.red("\nInterrupted.\n"));
-        process.exit(130);
+    catch (err) {
+        if (err?.name === "AbortError") {
+            process.stderr.write(chalk.red("\nInterrupted.\n"));
+            process.exit(130);
+        }
+        process.stderr.write(chalk.red(`error: ${err?.message ?? err}\n`));
+        process.exit(1);
+    }
+}
+async function promptProvider() {
+    const err = process.stderr;
+    err.write(chalk.bold("Select LLM provider:\n"));
+    err.write("  1) Gemini\n");
+    err.write("  2) OpenAI\n");
+    err.write("  3) Ollama (local)\n");
+    const choice = (await prompt("> ")).trim();
+    const provider = PROVIDERS[choice];
+    if (!provider) {
+        throw new Error("invalid provider selection");
+    }
+    return provider;
+}
+async function promptProviderConfig(provider) {
+    if (provider === "gemini") {
+        const key = (await promptHidden("Gemini API key: ")).trim();
+        if (!key) {
+            throw new Error("API key cannot be empty");
+        }
+        return { api_key: key };
+    }
+    if (provider === "openai") {
+        const key = (await promptHidden("OpenAI API key: ")).trim();
+        if (!key) {
+            throw new Error("API key cannot be empty");
+        }
+        return { api_key: key };
     }
+    if (provider === "ollama") {
+        const model = (await prompt("Ollama model (e.g. llama3, glm-5:cloud): ")).trim();
+        if (!model) {
+            throw new Error("Model cannot be empty");
+        }
+        const host = (await prompt("Ollama host [http://localhost:11434]: ")).trim()
+            || "http://localhost:11434";
+        return {
+            model,
+            host
+        };
+    }
+    throw new Error(`Unsupported provider: ${provider}`);
+}
+function prompt(label) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr,
+        terminal: true
+    });
+    return new Promise((resolve) => {
+        rl.question(label, (answer) => {
+            rl.close();
+            resolve(answer);
+        });
+    });
 }
 function promptHidden(label) {
     const err = process.stderr;
@@ -33,7 +98,7 @@ function promptHidden(label) {
         const rl = readline.createInterface({
             input: process.stdin,
             output: undefined,
-            terminal: true,
+            terminal: true
         });
         rl._writeToOutput = () => { };
         rl.question("", (answer) => {

package/dist/providers/base.d.ts

@@ -0,0 +1,8 @@
+export declare class LLMProviderError extends Error {
+    constructor(message: string);
+}
+export interface LLMProvider {
+    name: string;
+    validateConfig(): void;
+    generate(prompt: string): Promise<string>;
+}

package/dist/providers/base.js

@@ -0,0 +1,6 @@
+export class LLMProviderError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LLMProviderError";
+    }
+}

package/dist/providers/gemini.d.ts

@@ -0,0 +1,16 @@
+import { LLMProvider } from "./base.js";
+type GeminiConfig = {
+    api_key?: string;
+    model?: string;
+};
+export declare class GeminiProvider implements LLMProvider {
+    name: string;
+    private apiKey?;
+    private model;
+    private client?;
+    constructor(config?: GeminiConfig);
+    validateConfig(): void;
+    private getClient;
+    generate(prompt: string): Promise<string>;
+}
+export {};

package/dist/providers/gemini.js

@@ -0,0 +1,47 @@
+import { GoogleGenerativeAI } from "@google/generative-ai";
+import { LLMProviderError } from "./base.js";
+const DEFAULT_MODEL = "gemini-2.5-flash-lite";
+export class GeminiProvider {
+    name = "gemini";
+    apiKey;
+    model;
+    client;
+    constructor(config = {}) {
+        this.apiKey = config.api_key;
+        this.model = config.model ?? DEFAULT_MODEL;
+        this.validateConfig();
+    }
+    validateConfig() {
+        if (!this.apiKey || !this.apiKey.trim()) {
+            throw new LLMProviderError([
+                "Gemini provider requires an API key.",
+                "Run `explainthisrepo init` to configure it."
+            ].join("\n"));
+        }
+    }
+    getClient() {
+        if (this.client) {
+            return this.client;
+        }
+        this.client = new GoogleGenerativeAI(this.apiKey);
+        return this.client;
+    }
+    async generate(prompt) {
+        const genAI = this.getClient();
+        const model = genAI.getGenerativeModel({
+            model: this.model
+        });
+        try {
+            const result = await model.generateContent(prompt);
+            const text = result?.response?.text?.() ?? "";
+            if (!text.trim()) {
+                throw new LLMProviderError("Gemini returned no text");
+            }
+            return text.trim();
+        }
+        catch (err) {
+            const message = err?.message ? String(err.message) : String(err);
+            throw new LLMProviderError(`Gemini request failed: ${message}`);
+        }
+    }
+}

package/dist/providers/ollama.d.ts

@@ -0,0 +1,15 @@
+import { LLMProvider } from "./base.js";
+type OllamaConfig = {
+    model?: string;
+    host?: string;
+};
+export declare class OllamaProvider implements LLMProvider {
+    name: string;
+    private model;
+    private host;
+    constructor(config?: OllamaConfig);
+    validateConfig(): void;
+    doctor(): Promise<string[]>;
+    generate(prompt: string): Promise<string>;
+}
+export {};

package/dist/providers/ollama.js

@@ -0,0 +1,73 @@
+import { LLMProviderError } from "./base.js";
+const DEFAULT_MODEL = "llama3";
+const DEFAULT_HOST = "http://localhost:11434";
+export class OllamaProvider {
+    name = "ollama";
+    model;
+    host;
+    constructor(config = {}) {
+        this.model = config.model ?? DEFAULT_MODEL;
+        this.host = (config.host ?? DEFAULT_HOST).replace(/\/$/, "");
+        this.validateConfig();
+    }
+    validateConfig() {
+        if (!this.host.startsWith("http")) {
+            throw new LLMProviderError("Ollama host must be a valid URL (e.g. http://localhost:11434)");
+        }
+    }
+    async doctor() {
+        const results = [];
+        try {
+            const res = await fetch(`${this.host}/api/tags`, {
+                method: "GET"
+            });
+            if (res.ok) {
+                results.push("Ollama server reachable");
+            }
+            else {
+                results.push(`Ollama server responded with ${res.status}`);
+            }
+        }
+        catch {
+            results.push("Ollama server not reachable");
+        }
+        results.push(`model: ${this.model}`);
+        results.push(`host: ${this.host}`);
+        return results;
+    }
+    async generate(prompt) {
+        const url = `${this.host}/api/generate`;
+        const payload = {
+            model: this.model,
+            prompt,
+            stream: false
+        };
+        try {
+            const res = await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json"
+                },
+                body: JSON.stringify(payload)
+            });
+            if (!res.ok) {
+                throw new LLMProviderError(`Ollama server responded with ${res.status}`);
+            }
+            const data = await res.json();
+            const text = data?.response ?? "";
+            if (!text.trim()) {
+                throw new LLMProviderError("Ollama returned no text");
+            }
+            return text.trim();
+        }
+        catch (err) {
+            const message = err?.message ? String(err.message) : String(err);
+            throw new LLMProviderError([
+                "Failed to connect to Ollama.",
+                "Ensure Ollama is running locally.",
+                "Start it with: ollama serve",
+                `Error: ${message}`
+            ].join("\n"));
+        }
+    }
+}

package/dist/providers/openai.d.ts

@@ -0,0 +1,17 @@
+import { LLMProvider } from "./base.js";
+type OpenAIConfig = {
+    api_key?: string;
+    model?: string;
+};
+export declare class OpenAIProvider implements LLMProvider {
+    name: string;
+    private apiKey?;
+    private model;
+    private client?;
+    constructor(config?: OpenAIConfig);
+    validateConfig(): void;
+    private getClient;
+    generate(prompt: string): Promise<string>;
+    doctor(): string[];
+}
+export {};

package/dist/providers/openai.js

@@ -0,0 +1,57 @@
+import OpenAI from "openai";
+import { LLMProviderError } from "./base.js";
+const DEFAULT_MODEL = "gpt-4o-mini";
+export class OpenAIProvider {
+    name = "openai";
+    apiKey;
+    model;
+    client;
+    constructor(config = {}) {
+        this.apiKey = config.api_key;
+        this.model = config.model ?? DEFAULT_MODEL;
+        this.validateConfig();
+    }
+    validateConfig() {
+        if (!this.apiKey || !this.apiKey.trim()) {
+            throw new LLMProviderError([
+                "OpenAI provider requires an API key.",
+                "Run `explainthisrepo init` to configure it."
+            ].join("\n"));
+        }
+    }
+    getClient() {
+        if (this.client) {
+            return this.client;
+        }
+        this.client = new OpenAI({
+            apiKey: this.apiKey
+        });
+        return this.client;
+    }
+    async generate(prompt) {
+        const client = this.getClient();
+        try {
+            const response = await client.chat.completions.create({
+                model: this.model,
+                messages: [
+                    { role: "user", content: prompt }
+                ]
+            });
+            const text = response?.choices?.[0]?.message?.content ?? "";
+            if (!text.trim()) {
+                throw new LLMProviderError("OpenAI returned no text");
+            }
+            return text.trim();
+        }
+        catch (err) {
+            const message = err?.message ? String(err.message) : String(err);
+            throw new LLMProviderError(`OpenAI request failed: ${message}`);
+        }
+    }
+    doctor() {
+        return [
+            `OPENAI_API_KEY set: ${Boolean(this.apiKey)}`,
+            `model: ${this.model}`
+        ];
+    }
+}

package/dist/providers/registry.d.ts

@@ -0,0 +1,4 @@
+import { LLMProvider } from "./base.js";
+export declare function listProviders(): string[];
+export declare function getProvider(name: string): LLMProvider;
+export declare function getActiveProvider(override?: string): LLMProvider;

package/dist/providers/registry.js

@@ -0,0 +1,34 @@
+import { loadConfig } from "../config.js";
+import { LLMProviderError } from "./base.js";
+import { GeminiProvider } from "./gemini.js";
+import { OpenAIProvider } from "./openai.js";
+import { OllamaProvider } from "./ollama.js";
+const PROVIDER_REGISTRY = {
+    gemini: GeminiProvider,
+    openai: OpenAIProvider,
+    ollama: OllamaProvider,
+};
+export function listProviders() {
+    return Object.keys(PROVIDER_REGISTRY);
+}
+export function getProvider(name) {
+    const providerName = name.toLowerCase();
+    const Provider = PROVIDER_REGISTRY[providerName];
+    if (!Provider) {
+        throw new LLMProviderError(`Unknown LLM provider '${providerName}'`);
+    }
+    const config = loadConfig();
+    const providerConfig = config?.providers?.[providerName] ?? {};
+    return new Provider(providerConfig);
+}
+export function getActiveProvider(override) {
+    if (override) {
+        return getProvider(override);
+    }
+    const config = loadConfig();
+    const defaultProvider = config?.llm?.provider;
+    if (!defaultProvider) {
+        throw new LLMProviderError("No LLM provider configured. Run 'explainthisrepo init'.");
+    }
+    return getProvider(defaultProvider);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "explainthisrepo",
-  "version": "0.6.1",
-  "description": "CLI that generates plain English explanations of any codebase",
+  "version": "0.9.0",
+  "description": "CLI that generates plain-English explanations of any codebase",
   "license": "MIT",
   "type": "module",
   "author": "Caleb Wodi <calebwodi33@gmail.com>",
@@ -45,9 +45,11 @@
   },
   "dependencies": {
     "@google/generative-ai": "^0.24.1",
+    "@iarna/toml": "^2.2.5",
     "axios": "^1.13.2",
     "commander": "^14.0.3",
     "dotenv": "^17.2.3",
+    "openai": "^4.0.0",
     "ora": "^9.3.0"
   },
   "devDependencies": {