How ggyll/condo_gpt works
Project type and purpose
• Project Type: Full-stack web application with AI/LLM integration
File structure
Top-level files and directories:
• server.py – Flask web server (HTTP routing, request/response)
• main.py – Core orchestration: receives user query, dispatches to LLM agent and tools, formats output
• tools.py – Utility functions: dynamic SQL builder, database access layer, Google Maps API client
• prefix.py – System-message templates for GPT prompting
• boilerplate.py – Common code for rendering maps (Chart.js wrappers), PDF generation (ReportLab)
• templates/index.html – Frontend UI (single-page form, chart/map placeholders)
• static/ – Static assets (JS for Chart.js, CSS, images)
• sample_db.sql – Schema + sample data for PostgreSQL
• requirements.txt – Dependencies (Flask, psycopg2, LangChain, OpenAI, Chart.js shipped via CDN)
README for additional insights
• Stack: Python 3.x, Flask, PostgreSQL, LangChain/LangGraph, OpenAI API, Google Maps API, Chart.js, ReportLab
• Features: NLP interface → dynamic SQL → DB queries → data visualization → PDF reporting
• Workflow hints: server.py calls main.py; main.py loads prefix.py; uses tools.py; boilerplate for charts & PDFs
a. Main components:
1. User Interface (Browser)
– HTML/CSS/JS (index.html + static)
– Chart.js for frontend graphs
2. Flask Backend (server.py)
– HTTP endpoints (/, /query, /report, /clear)
3. Application Logic (main.py + prefix.py + examples.py + sandbox.py)
– Natural language parsing & prompt construction
– LangChain/LangGraph agent orchestration
4. Tools Layer (tools.py)
– Database client (psycopg2/PostgreSQL)
– Dynamic SQL generator
– Google Maps API client
5. Visualization & Reporting (boilerplate.py)
– Chart.js config helpers (server-side JSON for frontend)
– ReportLab PDF generator
6. Data Store (PostgreSQL)
– Condo data tables (from sample_db.sql)
7. External Services
– OpenAI API (GPT model calls)
– Google Maps/Places API
b. Relationships & data flows:
• User submits question (Browser → Flask)
• Flask → main.py: apply prefix.py, form prompt, call LangChain agent
• LangChain agent → OpenAI API → returns SQL or high-level answer
• If SQL returned: main.py → tools.py → PostgreSQL → result set
• For location queries: tools.py → Google Maps API → geocoding/directions
• main.py → boilerplate.py → chart config or PDF buffer
• Flask → Browser: JSON payload for Chart.js or PDF file
c. Architectural patterns & principles:
• Layered architecture: Presentation (UI) → Application (Flask + orchestration) → Tools/Service → Data
• Use of agent pattern (LangChain) to encapsulate LLM interactions
• Separation of concerns: prompt templates (prefix.py) vs. business logic (main.py) vs. external integrations (tools.py)
d. Key technologies:
• Flask (web server)
• LangChain & LangGraph (agent framework)
• OpenAI GPT (LLM)
• psycopg2/PostgreSQL (database)
• Google Maps API (geocoding/directions)
• Chart.js (front-end visualization)
• ReportLab (PDF generation)