How developmentseed/llllm works
Project Type & Purpose
• This is a Python-based, cloud-deployed “full-stack” application whose core is an LLM-powered agent orchestrating custom geospatial tools.
• It provides:
• A Streamlit front-end (app.py) for interactive use
• A LangChain agent (agents/l4m_agent.py) that routes queries to tools
• A suite of modular geospatial tools under tools/ (GeoPy, OSMnx, Mercantile, STAC)
• Deployment artifacts (Dockerfile, Helm charts, GitHub Actions workflows) targeting Kubernetes
File Structure
• Top-level:
• app.py – Streamlit UI entrypoint
• agents/ – Agent construction logic
• tools/ – Business-logic modules (each tool lives in its own subpackage)
• nbs/ – Example notebooks (no runtime role)
• deployment/ – Helm charts (templates/ + values.yaml), raw k8s manifests, CI/CD
• Config & infra:
• Dockerfile – containerizes the app
• .github/workflows/build_and_deploy.yaml – CI/CD pipeline to build image & deploy via Helm
• environment.yaml – Conda/mamba environment spec
README Insights
• Describes tool architecture: each tool is a BaseTool subclass or Tool dataclass
• Shows how the agent picks tools dynamically based on LLM responses
• Indicates use of external LLMs (OpenAI API), geospatial libraries, and a Streamlit UI
Main Components
a. Frontend Layer
• Streamlit UI (app.py)
• Represents user interactions (input form, map display)
b. Agent Layer
• LangChain Agent (agents/l4m_agent.py)
• Decision-making “router” that chooses which Tool to invoke
c. Tool Layer
• MercantileTool, GeoPyTool, OSMnxTool, STACTool modules
• Each module wraps geospatial library/API calls
d. External Services
• OpenAI API (LLM calls)
• Geospatial data sources (OSM over HTTP, STAC endpoints, GeoPy geocoding services)
e. Infrastructure & Deployment
• Docker Container
• Kubernetes Cluster (Ingress, Cert Manager, Streamlit Deployment)
• CI/CD (GitHub Actions → Docker Build → Helm Chart → K8s)
Relationships & Data Flow
1. User interacts with Streamlit UI
2. UI sends requests to the Agent Layer
3. Agent invokes one or more Tools based on LLM responses
4. Tools call External Services (OpenAI + geospatial APIs)
5. Service responses flow back → Agent aggregates → UI displays results
6. CI/CD pipeline builds & deploys Docker image to Kubernetes (side flow, triggered by Git push)
Architectural Patterns & Design Principles
• Layered architecture: Clear layering (UI → Agent → Tools → External)
• Modularization: Each tool is a separate submodule, enabling easy extension
• Infrastructure as code: Helm charts + GitHub Actions for reproducible deployment
• Dependency injection: Agent constructed with pluggable tool list
Technologies & Frameworks
• Python 3.x, Streamlit, LangChain
• Geospatial libs: GeoPy, OSMnx, Mercantile, STAC clients
• Containerization: Docker
• Orchestration: Kubernetes, Helm
• CI/CD: GitHub Actions
• Environment management: Conda/Mamba (environment.yaml)
Detailed Capture of Architectural Elements
• Agent’s tools parameter injection (list of Tool objects)
• How Helm’s streamlit.yaml template maps to the deployed Pod + Ingress
• Environment variable (OPENAI_API_KEY) usage in container