# developmentseed/llllm architecture

> Architecture diagram of the GitHub repository developmentseed/llllm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/developmentseed/llllm
- Repository: https://github.com/developmentseed/llllm

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Layers
  subgraph "Application Layer"
    direction TB
    User["User"]:::external
    UI["Streamlit UI\n(app.py)"]:::ui
    Agent["LangChain Agent\n(agents/l4m_agent.py)"]:::logic
    subgraph "Tool Layer"
      direction TB
      subgraph GeoPyTool
        direction TB
        GeoCode["geocode()\n(tools/geopy/geocode.py)"]:::tool
        Distance["distance()\n(tools/geopy/distance.py)"]:::tool
      end
      MercTool["MercantileTool\n(tools/mercantile_tool.py)"]:::tool
      subgraph OSMnxTool
        direction TB
        Geometry["geometry()\n(tools/osmnx/geometry.py)"]:::tool
        Network["network()\n(tools/osmnx/network.py)"]:::tool
      end
      STACTool["STACTool\n(tools/stac/search.py)"]:::tool
    end
  end

  subgraph "External Services"
    direction TB
    OpenAI["OpenAI API"]:::external
    OSMAPI["OSM over HTTP"]:::external
    STACAPI["STAC Endpoints"]:::external
    GeoPySvc["GeoPy Geocode Service"]:::external
  end

  subgraph "Infrastructure & Deployment"
    direction TB
    CI["GitHub Actions\n(.github/workflows/build_and_deploy.yaml)"]:::infra
    Docker["Docker Build\n(Dockerfile)"]:::infra
    EnvSpec["Environment Spec\n(environment.yaml)"]:::infra
    subgraph "Helm Charts"
      direction TB
      Chart["Chart.yaml"]:::infra
      Values["values.yaml"]:::infra
      StreamlitYAML["streamlit.yaml"]:::infra
      IngressYAML["ingress.yaml"]:::infra
      CertYAML["letsencrypt-cert-issuer.yaml"]:::infra
      SecretsYAML["secrets.yaml"]:::infra
    end
    ConfigMap["ConfigMap\n(configmap.yaml)"]:::infra
    K8s["Kubernetes Cluster\n(Pods, Ingress, Cert-Manager)"]:::infra
  end

  %% Relationships: Application flow
  User -->|"interacts with"| UI
  UI -->|"sends query to"| Agent
  Agent -->|"invokes"| GeoCode
  Agent -->|"invokes"| Distance
  Agent -->|"invokes"| MercTool
  Agent -->|"invokes"| Geometry
  Agent -->|"invokes"| Network
  Agent -->|"invokes"| STACTool
  GeoCode -->|"calls"| GeoPySvc
  Distance -->|"calls"| GeoPySvc
  MercTool -->|"calls"| OSMAPI
  Geometry -->|"calls"| OSMAPI
  Network -->|"calls"| OSMAPI
  STACTool -->|"calls"| STACAPI
  Agent -->|"requests LLM"| OpenAI
  OpenAI -->|"response"| Agent
  Agent -->|"returns results to"| UI
  UI -->|"displays to"| User

  %% CI/CD & Infra flow
  CI -->|"triggers build"| Docker
  Docker -->|"packages image"| Chart
  Chart -->|"uses values"| Values
  Chart -->|"includes templates"| StreamlitYAML
  Chart -->|"includes templates"| IngressYAML
  Chart -->|"includes templates"| CertYAML
  Chart -->|"includes templates"| SecretsYAML
  Chart -->|"refs config"| ConfigMap
  Chart -->|"deploys to"| K8s

  %% Click events
  click UI "https://github.com/developmentseed/llllm/blob/main/app.py"
  click Agent "https://github.com/developmentseed/llllm/blob/main/agents/l4m_agent.py"
  click GeoCode "https://github.com/developmentseed/llllm/blob/main/tools/geopy/geocode.py"
  click Distance "https://github.com/developmentseed/llllm/blob/main/tools/geopy/distance.py"
  click MercTool "https://github.com/developmentseed/llllm/blob/main/tools/mercantile_tool.py"
  click Geometry "https://github.com/developmentseed/llllm/blob/main/tools/osmnx/geometry.py"
  click Network "https://github.com/developmentseed/llllm/blob/main/tools/osmnx/network.py"
  click STACTool "https://github.com/developmentseed/llllm/blob/main/tools/stac/search.py"
  click CI "https://github.com/developmentseed/llllm/blob/main/.github/workflows/build_and_deploy.yaml"
  click Docker "https://github.com/developmentseed/llllm/tree/main/Dockerfile"
  click EnvSpec "https://github.com/developmentseed/llllm/blob/main/environment.yaml"
  click Chart "https://github.com/developmentseed/llllm/blob/main/deployment/helm/Chart.yaml"
  click Values "https://github.com/developmentseed/llllm/blob/main/deployment/helm/values.yaml"
  click StreamlitYAML "https://github.com/developmentseed/llllm/blob/main/deployment/helm/templates/streamlit.yaml"
  click IngressYAML "https://github.com/developmentseed/llllm/blob/main/deployment/helm/templates/ingress.yaml"
  click CertYAML "https://github.com/developmentseed/llllm/blob/main/deployment/helm/templates/letsencrypt-cert-issuer.yaml"
  click SecretsYAML "https://github.com/developmentseed/llllm/blob/main/deployment/helm/templates/secrets.yaml"
  click ConfigMap "https://github.com/developmentseed/llllm/blob/main/deployment/k8s/configmap.yaml"

  %% Styles
  classDef ui fill:#cce5ff,stroke:#004085,color:#004085;
  classDef logic fill:#d4edda,stroke:#155724,color:#155724;
  classDef tool fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
  classDef external fill:#fff3cd,stroke:#856404,color:#856404;
  classDef infra fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
