How apideck-libraries/describer works
Project type and purpose
• Describer is a Python-based command-line tool (an open-source CLI application) whose purpose is to analyze arbitrary codebases using Google’s Gemini AI.
• It strings together three existing libraries—files-to-prompt, llm, and llm-gemini—to scan directories, build AI prompts, invoke the Gemini API, and render AI-generated analyses (architecture overviews, bug reports, documentation, etc.).
File structure
• Top-level files:
• pyproject.toml – packaging, dependencies, entry point
• README.md, codebase-overview.md – docs
• describer/cli.py – the main CLI entrypoint
• describer/core.py – core logic (scanning, prompt building, invoking AI)
• tests/ – unit tests for core functionality and output
• No frontend vs. backend: it’s a single binary CLI tool.
• External-integration points: importing files-to-prompt, llm, llm-gemini.
Key components
a. User and CLI layer
– User invokes describer command with arguments (directory path, prompt override, output flags).
– CLI parser (click or argparse in cli.py).
b. File Scanner
– Uses files-to-prompt library to walk the target directory, honor .gitignore, filter/exclude patterns.
c. Prompt Builder
– Aggregates scanned files into prompts (chunks, metadata) for LLM consumption.
d. LLM Client
– llm library instance configured with llm-gemini plugin.
– Sends prompt to Google Gemini API, waits for the completion.
e. Output Formatter & Writer
– Receives AI response, formats as markdown or plain text.
– Writes to stdout or to an output file (per the –o/--output flag).
f. External Service
– Google AI Studio / Gemini API endpoint, authenticated via API key.
g. Test Harness (auxiliary)
– Unittests in tests/ validate core.py logic and output file generation.
Relationships and data flows
User → CLI parser → File Scanner → Prompt Builder → LLM Client → Gemini API
Gemini API → LLM Client → Output Formatter → User (stdout or file)
• Optional flags influencing behavior: model selection (-m), exclude patterns, ignore-gitignore.
Architectural patterns and design principles
• Single-responsibility modules:
• cli.py handles argument parsing & orchestration
• core.py handles scanning + prompt + AI calls
• Pluggable LLM backend: llm abstraction lets you swap in other models.
• Respect for user configuration (.gitignore, exclude patterns, API key).
• Minimalist, linear pipeline: Stage-based data flow (scan → build → call → output).
Detailed capture of essential elements
• How the llm-gemini plugin is loaded by llm.
• Respect for .gitignore and exclude patterns in scanning stage.
• Tests as a separate module that invokes core logic and validates output.