How devgomesai/web-agent works
Project type and purpose
• This is a standalone CLI tool (Python package) that performs AI-driven web searches, analyzes the results, and displays a rich, formatted response in the terminal.
• It leverages Brave Search for crawling the web, and one or more AI providers (OpenAI GPT models or Google Gemini) for analysis.
File structure
• Top-level files:
• cli_web_agent.py – the entry point for the CLI (likely powered by Typer)
• pyproject.toml – build, dependencies, and packaging configuration
• .claude/settings.local.json – local settings for Claude agent framework
• Lock files (uv.lock) and environment/version config (.python-version)
• No separate “frontend” or “backend” folders: this is a single Python module/package.
README insights
• Core workflow:
1. Query Processing
2. Web Search (Brave API)
3. AI Analysis (OpenAI/Google)
4. Formatting & Display (Rich + Typer CLI)
5. Cost & Token Tracking
• Key dependencies: PydanticAI (agent framework), Typer (CLI parsing), Rich (UI), Brave Search API, OpenAI/Google AI.
Main components
a. CLI Interface (Typer + cli_web_agent.py)
b. Configuration Manager (env variables, .env, Pydantic models)
c. Query Processor Module (parses and normalizes user input)
d. Web Search Service Adapter (Brave Search API client)
e. AI Analysis Service Adapter (OpenAI / Google AI clients)
f. Analysis Orchestrator (coordinates search + AI calls)
g. Output Formatter (Rich panels, tables, progress bars)
h. Cost & Token Tracker (records usage, estimates cost)
i. Packaging / Build (pyproject.toml, build artifacts)
j. External Services (Brave Search, OpenAI, Google AI)
Relationships & interactions
• CLI → Query Processor → Analysis Orchestrator
• Analysis Orchestrator ↔ Web Search Service Adapter
• Analysis Orchestrator ↔ AI Analysis Service Adapter
• Analysis Orchestrator → Cost & Token Tracker
• Analysis Orchestrator → Output Formatter → CLI stdout
• Configuration Manager injects API keys and model settings into Service Adapters and Query Processor
• Packaging / Build is orthogonal – shows how the tool is distributed
Architectural Patterns & Design Principles
• Modular adapters for external services, enabling swapping AI providers
• Separation of concerns: parsing, searching, analyzing, formatting, and tracking are distinct modules
• Dependency injection via environment/config manager
• Single‐process, synchronous orchestration (could evolve to async if needed)
Putting it all together
• Related components inside a boundary titled “Web Agent CLI Application.”
• At the bottom or side, show “Packaging & Distribution” (pyproject.toml → dist/*.whl, .tar.gz).