# langchain-ai/streamlit-agent architecture

> Architecture diagram of the GitHub repository langchain-ai/streamlit-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/langchain-ai/streamlit-agent
- Repository: https://github.com/langchain-ai/streamlit-agent

## Overview

##### What this project is (type + purpose)
This repo is **not a single “system” with one backend**; it’s a **collection of reference Streamlit apps** demonstrating different **LangChain agent patterns** (streaming, memory, MRKL/tools, RAG over documents, SQL DB chat, pandas DF chat, feedback + LangSmith tracing).

- A **shared runtime/container + shared libraries/utilities** (LangChain, Streamlit, callbacks)
- Multiple **entrypoint apps** under `streamlit_agent/*.py` that each compose slightly different agent/tool chains
- A set of **external services** (OpenAI API, search providers, LangSmith, etc.) and **local data sources** (documents, SQLite DB, pickled runs)

##### Read the file tree as architecture clues
Top-level signals:
- `streamlit_agent/` is the main Python package with multiple Streamlit entrypoints:
- `basic_streaming.py`, `basic_memory.py`, `mrkl_demo.py`, `minimal_agent.py`, `search_and_chat.py`, `simple_feedback.py`, `chat_with_documents.py`, `chat_with_sql_db.py`, `chat_pandas_df.py`
- `streamlit_agent/callbacks/` contains callback plumbing:
- `capturing_callback_handler.py` (key for “how streaming/tracing/observability works”)
- `streamlit_agent/Chinook.db` is a **local SQLite database** used by the SQL chat app.
- `streamlit_agent/runs/*.pickle` suggests **stored run artifacts / cached sessions / example traces**.
Infra / packaging / execution:
- `pyproject.toml` (Poetry deps)
- `Dockerfile` + `docker-compose.yml` (containerized execution; compose used to select which Streamlit app to run)
- `.devcontainer/` (Codespaces/devcontainer)
- `.pre-commit-config.yaml` (dev workflow quality gates)

##### What the README adds
The README explicitly frames each file as a **separate app** and calls out key integrations:
- Streamlit **callback integration** (for token streaming / UI updates)
- `StreamlitChatMessageHistory` (memory stored in Streamlit session state)
- `streamlit-feedback` + LangSmith links (feedback UI + trace observability)
It also hints at external requirements like `OPENAI_API_KEY`.

##### Optional External Tools/Services
- Search (for `minimal_agent.py`, `search_and_chat.py`)
- **LangSmith** (for tracing/observability; emphasized by `simple_feedback.py`)
##### Local/Embedded Data Sources
- SQLite: `Chinook.db` (for `chat_with_sql_db.py`)
- Pickled runs: `streamlit_agent/runs/*.pickle` (optional persisted artifacts)

- Browser → Streamlit: user prompts, UI events, feedback clicks
- Streamlit → LLM API: prompt/tool context → completion (streaming tokens)
- Streamlit ↔ Local DB/documents: read queries, retrieval, embeddings (if used)
- Streamlit → LangSmith: traces/spans/metadata (if enabled)
- Streamlit → Search API: query → results (if enabled)

- **UI Layer (Streamlit widgets)**
- **App Orchestrators (each `*.py` entrypoint)**
As separate components because they are effectively separate “products”:
- `basic_streaming.py`
- `basic_memory.py`
- `mrkl_demo.py`
- `minimal_agent.py`
- `search_and_chat.py`
- `simple_feedback.py`
- `chat_with_documents.py`
- `chat_with_sql_db.py`
- `chat_pandas_df.py`
- **LangChain Core Abstractions**
- LLM (ChatOpenAI)
- Agents / Chains
- Tools (Search tool, SQL tool, Python REPL tool, Retriever tool, etc.)
- Memory (StreamlitChatMessageHistory / session state)
- **Callbacks / Streaming**
- `callbacks/capturing_callback_handler.py` (show as cross-cutting concern)
- **State & Persistence**
- Streamlit session state (memory)
- Optional local artifacts (`runs/*.pickle`)

##### `basic_streaming.py`
- UI → ChatOpenAI (streaming)
- ChatOpenAI → Callback handler → UI incremental rendering

##### `basic_memory.py`
- UI ↔ StreamlitChatMessageHistory (session state)
- UI + Memory → LLM → response → Memory append

##### `mrkl_demo.py`
- UI → Agent (MRKL-style)
- Agent → Tool router → {Search tool, other tools} → results
- Agent → LLM (planning + final answer)

##### `minimal_agent.py`
- UI → Agent
- Agent → Search API tool → results → LLM synthesis

##### `search_and_chat.py`
- Combines: Memory + Search tool + LLM streaming

##### `simple_feedback.py`
- UI → LLM
- UI → Feedback component (`streamlit-feedback`)
- Streamlit → LangSmith (trace IDs + links)

##### `chat_with_documents.py`
- Document ingest (upload/load) → chunking/embedding (if used) → vector store/retriever
- UI query → Retriever → context → LLM → answer with citations (if implemented)

##### `chat_with_sql_db.py`
- UI question → SQL agent/tooling → SQLite (`Chinook.db`) → query results → LLM explanation

##### `chat_pandas_df.py`
- UI question → PythonAstREPLTool / pandas ops → computed result → LLM response
(Call out security boundary: “arbitrary code execution risk”)

##### Architectural patterns to highlight (project-specific)
- **Composable “agent + tools” pattern** (LangChain): agents orchestrate tool calls, then synthesize final responses.
- **Cross-cutting callbacks** for:
- Token streaming
- Capturing intermediate steps / traces
- **Session-based memory**: Streamlit’s session state as the store for conversation history.
- **Pluggable data backends**:
- Documents (RAG)
- SQL (structured)
- DataFrames (in-memory analytics)
- **Observability loop** (simple_feedback + LangSmith): trace → user feedback → iterate.

##### Diagramming guidance (what to include explicitly)

- “Browser (User)”
- “Streamlit App (choose entrypoint)”
- “LangChain (Agent/Chain + Tools + Memory)”
- “Callback Handlers (streaming/tracing)”
- “External LLM API”
- “External Tools” (Search, LangSmith)
- “Data Sources” (SQLite Chinook.db, Documents, DataFrame, Pickle artifacts)

- “Prompt + chat history”
- “Tool call (query)”
- “SQL query / result set”
- “Retrieved chunks”
- “Streaming tokens”
- “Trace spans / metadata”
- “Feedback (thumbs up/down + text)”

This avoids overfitting into a fake “frontend/backend/database” split and instead captures the essential architecture: **Streamlit UI + LangChain orchestration + external LLM/tools + optional local data + callbacks/memory**.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Level 0: Context / Overview
    %% =========================
    U["Browser (User)"]:::external

    subgraph "Containerized Runtime"
        DC["docker-compose (select app)"]:::infra
        DF["Docker Image / Streamlit Server (Python)"]:::infra
        PKG["streamlit_agent (apps package)"]:::pkg

        DC -->|"runs"| DF
        DF -->|"loads"| PKG
    end

    LLM["External LLM API (e.g., OpenAI)"]:::external
    SEARCH["External Search API"]:::external
    LSM["LangSmith (tracing/observability)"]:::external

    subgraph "Local / Embedded Data Sources"
        DB[("SQLite DB (Chinook.db)")]:::data
        DOCS["Local Documents / File Uploads"]:::doc
        DF_SRC["Pandas DataFrame Source (CSV/DF in memory)"]:::doc
        RUNS[("Pickled Runs (*.pickle)")]:::data
    end

    U -->|"prompts,UIevents,feedback"| DF
    DF -->|"prompt+context"| LLM
    LLM -->|"streamingtokens"| DF

    DF -.->|"toolquery"| SEARCH
    SEARCH -.->|"results"| DF

    DF -.->|"traces,spans,metadata"| LSM

    DF -->|"read/write"| DB
    DF -->|"load/upload"| DOCS
    DF -->|"load"| DF_SRC
    DF -.->|"persist/restore"| RUNS

    %% ==================================
    %% Level 1: Inside Streamlit Server
    %% ==================================
    subgraph "Streamlit Server Internals (shared building blocks)"
        UI["UI Layer (Streamlit widgets)"]:::frontend

        subgraph "Callbacks (cross-cutting)"
            CB_DIR["callbacks/"]:::shared
            CB["Capturing Callback Handler"]:::shared
            CB_DIR -->|"contains"| CB
        end

        subgraph "LangChain Core"
            LC["LangChain (agents/chains)"]:::compute
            TOOLS["Tools (Search / SQL / Retriever / Python REPL)"]:::compute
            MEM["Memory (Streamlit session state history)"]:::compute
            LC -->|"uses"| TOOLS
            LC -->|"uses"| MEM
        end

        subgraph "State & Artifacts"
            SS["Streamlit Session State"]:::data
            RUNS_DIR[("runs/ (pickle artifacts)")]:::data
            SS -->|"stores"| MEM
        end

        UI -->|"userinput"| LC
        LC -->|"callbacks"| CB
        CB -->|"UIupdates"| UI
        LC -->|"LLMcalls"| LLM
        LLM -->|"streamingtokens"| CB

        RUNS_DIR -.->|"optionalcache"| LC
    end

    DF -->|"serves"| UI

    %% ==================================
    %% Level 2: Per-App Mini Diagrams
    %% ==================================
    subgraph "Apps (each is a separate Streamlit entrypoint)"
        direction TB

        subgraph "basic_streaming"
            BS["basic_streaming.py"]:::app
            BS -->|"prompt"| LLM
            LLM -->|"streamingtokens"| CB
            CB -->|"incrementalrender"| UI
        end

        subgraph "basic_memory"
            BM["basic_memory.py"]:::app
            BM -->|"read/write"| SS
            BM -->|"prompt+history"| LLM
            LLM -->|"response"| BM
            BM -->|"append"| SS
        end

        subgraph "mrkl_demo"
            MRKL["mrkl_demo.py"]:::app
            MRKL -->|"agentplan"| LLM
            MRKL -->|"toolcalls"| TOOLS
            TOOLS -.->|"searchresults"| MRKL
            MRKL -->|"finalanswer"| UI
        end

        subgraph "minimal_agent"
            MINA["minimal_agent.py"]:::app
            MINA -->|"toolquery"| SEARCH
            SEARCH -->|"results"| MINA
            MINA -->|"synthesize"| LLM
        end

        subgraph "search_and_chat"
            SAC["search_and_chat.py"]:::app
            SAC -->|"memory"| SS
            SAC -.->|"searchtool"| SEARCH
            SAC -->|"LLMstream"| LLM
            LLM -->|"streamingtokens"| CB
        end

        subgraph "simple_feedback"
            SFB["simple_feedback.py"]:::app
            SFB -->|"LLMcall"| LLM
            SFB -.->|"trace/spans"| LSM
            UI -.->|"thumbs+text"| SFB
            SFB -.->|"feedbackmetadata"| LSM
        end

        subgraph "chat_with_documents (RAG)"
            CWD["chat_with_documents.py"]:::app
            CWD -->|"upload/load"| DOCS
            CWD -->|"retrievechunks"| LC
            LC -->|"context+question"| LLM
        end

        subgraph "chat_with_sql_db"
            CSQL["chat_with_sql_db.py"]:::app
            CSQL -->|"SQLtool"| TOOLS
            TOOLS -->|"SQLquery"| DB
            DB -->|"resultset"| TOOLS
            TOOLS -->|"explain"| LLM
        end

        subgraph "chat_pandas_df (unsafe execution zone)"
            CPD["chat_pandas_df.py"]:::app
            REPL["PythonAstREPLTool / pandas ops"]:::unsafe
            CPD -->|"data"| DF_SRC
            CPD -->|"codeexec"| REPL
            REPL -->|"computedresult"| CPD
            CPD -->|"finalresponse"| LLM
        end
    end

    PKG -->|"containsentrypoints"| BS
    PKG -->|"containsentrypoints"| BM
    PKG -->|"containsentrypoints"| MRKL
    PKG -->|"containsentrypoints"| MINA
    PKG -->|"containsentrypoints"| SAC
    PKG -->|"containsentrypoints"| SFB
    PKG -->|"containsentrypoints"| CWD
    PKG -->|"containsentrypoints"| CSQL
    PKG -->|"containsentrypoints"| CPD

    %% =========================
    %% Repo/Workflow (supporting)
    %% =========================
    subgraph "Repo Tooling / Metadata"
        direction TB
        PP["Poetry packaging (pyproject.toml)"]:::infra
        DOC["README (docs)"]:::infra
        PRE["pre-commit hooks"]:::infra
        DEV["Devcontainer"]:::infra
        CLR["clear_results.py"]:::infra

        PP -->|"declaresdeps"| DF
        DEV -->|"devenv"| DF
        CLR -->|"clears"| RUNS_DIR
    end

    %% =========================
    %% Click Events (component mapping)
    %% =========================
    click PKG "https://github.com/langchain-ai/streamlit-agent/tree/main/streamlit_agent/"
    click BS "https://github.com/langchain-ai/streamlit-agent/blob/main/streamlit_agent/basic_streaming.py"
    click BM "https://github.com/langchain-ai/streamlit-agent/blob/main/streamlit_agent/basic_memory.py"
    click MRKL "https://github.com/langchain-ai/streamlit-agent/blob/main/streamlit_agent/mrkl_demo.py"
    click MINA "https://github.com/langchain-ai/streamlit-agent/blob/main/streamlit_agent/minimal_agent.py"
    click SAC "https://github.com/langchain-ai/streamlit-agent/blob/main/streamlit_agent/search_and_chat.py"
    click SFB "https://github.com/langchain-ai/streamlit-agent/blob/main/streamlit_agent/simple_feedback.py"
    click CWD "https://github.com/langchain-ai/streamlit-agent/blob/main/streamlit_agent/chat_with_documents.py"
    click CSQL "https://github.com/langchain-ai/streamlit-agent/blob/main/streamlit_agent/chat_with_sql_db.py"
    click CPD "https://github.com/langchain-ai/streamlit-agent/blob/main/streamlit_agent/chat_pandas_df.py"
    click CB_DIR "https://github.com/langchain-ai/streamlit-agent/tree/main/streamlit_agent/callbacks/"
    click CB "https://github.com/langchain-ai/streamlit-agent/blob/main/streamlit_agent/callbacks/capturing_callback_handler.py"
    click DB "https://github.com/langchain-ai/streamlit-agent/blob/main/streamlit_agent/Chinook.db"
    click RUNS_DIR "https://github.com/langchain-ai/streamlit-agent/tree/main/streamlit_agent/runs/"
    click RUNS "https://github.com/langchain-ai/streamlit-agent/tree/main/streamlit_agent/runs/"
    click CLR "https://github.com/langchain-ai/streamlit-agent/blob/main/streamlit_agent/clear_results.py"
    click DF "https://github.com/langchain-ai/streamlit-agent/tree/main/Dockerfile"
    click DC "https://github.com/langchain-ai/streamlit-agent/blob/main/docker-compose.yml"
    click PP "https://github.com/langchain-ai/streamlit-agent/blob/main/pyproject.toml"
    click DEV "https://github.com/langchain-ai/streamlit-agent/blob/main/.devcontainer/devcontainer.json"
    click DOC "https://github.com/langchain-ai/streamlit-agent/blob/main/README.md"
    click PRE "https://github.com/langchain-ai/streamlit-agent/blob/main/.pre-commit-config.yaml"

    %% Extra pickles (mapped)
    click RUNS_DIR "https://github.com/langchain-ai/streamlit-agent/tree/main/streamlit_agent/runs/"
    click RUNS "https://github.com/langchain-ai/streamlit-agent/tree/main/streamlit_agent/runs/"
    click UI "https://github.com/langchain-ai/streamlit-agent/tree/main/streamlit_agent/"
    click LC "https://github.com/langchain-ai/streamlit-agent/tree/main/streamlit_agent/"
    click TOOLS "https://github.com/langchain-ai/streamlit-agent/tree/main/streamlit_agent/"
    click MEM "https://github.com/langchain-ai/streamlit-agent/tree/main/streamlit_agent/"
    click SS "https://github.com/langchain-ai/streamlit-agent/tree/main/streamlit_agent/"
    click REPL "https://github.com/langchain-ai/streamlit-agent/blob/main/streamlit_agent/chat_pandas_df.py"

    %% =========================
    %% Styles
    %% =========================
    classDef external fill:#eef6ff,stroke:#2563eb,stroke-width:1.5px,color:#0b2a55
    classDef infra fill:#fff7ed,stroke:#c2410c,stroke-width:1.5px,color:#4a1b07
    classDef pkg fill:#f0fdf4,stroke:#16a34a,stroke-width:1.5px,color:#052e12
    classDef frontend fill:#fdf2f8,stroke:#be185d,stroke-width:1.5px,color:#4a044e
    classDef compute fill:#ecfeff,stroke:#0891b2,stroke-width:1.5px,color:#083344
    classDef shared fill:#f5f3ff,stroke:#6d28d9,stroke-width:1.5px,color:#2e1065
    classDef data fill:#fff1f2,stroke:#be123c,stroke-width:1.5px,color:#4c0519
    classDef doc fill:#fefce8,stroke:#a16207,stroke-width:1.5px,color:#422006
    classDef app fill:#f1f5f9,stroke:#334155,stroke-width:1.5px,color:#0f172a
    classDef unsafe fill:#fee2e2,stroke:#b91c1c,stroke-width:2px,color:#450a0a,stroke-dasharray: 6 4
```
