How ashushekar/maven_code works
Project Type and Purpose
• This is a Python-based, full-stack curriculum/demo application that teaches LangChain/LangGraph concepts through week-by-week agent workflows.
• It exposes a Gradio UI (frontend) and a CLI entry point that drives various “week” modules (backend), orchestrating chat agents, retrieval patterns, and tool integrations.
File Structure
• Top-level “code/” directory houses:
• run.py – CLI launcher for different weeks/parts
• requirements.txt – dependency list
• perplexia_ai/ – main package
• Inside perplexia_ai/:
• app.py – Gradio wiring & factory dispatch logic
• core/ – abstract ChatInterface and shared chat logic
• tools/ – reusable LangChain-compatible utilities (e.g., calculator)
• week1/, week2/, week3/ – progressively complex agent implementations
• docs/ – system_architecture.drawio, PDFs, markdown walkthrough
• Configuration: .python-version, .gitignore, and environment variables (for OpenAI, Tavily, MCP credentials).
README Insights
• Describes multi-week capabilities: prompting foundations, RAG, agentic workflows
• Highlights factory pattern (create_chat_implementation per week)
• Mentions external services: OpenAI chat models, Tavily search, PDF storage, optional MCP servers
Main Components
a. Presentation Layer
– run.py CLI launcher
– Gradio server (app.py) with endpoints and UI components
b. Orchestration Layer
– WeekFactory module in app.py (dispatches to week1/2/3 modules)
– ChatInterface abstraction (core/chat_interface.py)
c. Business Logic Layer (Week Modules)
– week1/: Prompting, stateful memory, calculator tool
– week2/: Retrieval workflows (web + PDF RAG)
– week3/: Agentic workflows, research graphs, bookmarking MCP server
d. Utilities Layer
– tools/: reusable utilities invoked by agents (e.g., calculator.py)
e. Data & Docs
– Local PDF docs in docs/ (used for RAG)
– bookmarks.json (week3 persistent state)
f. External Services
– OpenAI (chat completions)
– Tavily (live web search)
– MCP Server (bookmarking)
Relationships and Data Flows
• run.py → Gradio UI → API handlers in app.py
• UI handlers call WeekFactory.create_chat_implementation(week, part)
• Chat implementation invokes ChatInterface methods, leveraging core abstractions
• Agents call utilities in tools/ and retrieval routines in week modules
• Retrieval agents read local PDFs or call Tavily, merge evidence
• Agents issue OpenAI API requests for LLM responses
• week3 agents may call an external MCP bookmarking service (HTTP)
• Responses stream back through the factory to the Gradio frontend
Architectural Patterns & Design Principles
• Layered Architecture: clear separation between UI, orchestration, business logic, utilities, and external services
• Factory Pattern: week-based dispatch in app.py
• Dependency Injection: ChatInterface and tool modules plugged into agents
• Modular Plugin-style Weeks: each week is a self-contained folder with consistent API