# shaunakbale/country-information-ai-agent architecture

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

- Interactive diagram: https://gitdiagram.com/shaunakbale/country-information-ai-agent
- Repository: https://github.com/shaunakbale/country-information-ai-agent

## Overview

This is a **single-service Python application** with a **Streamlit UI** that hosts a **conversational AI agent**. The agent uses **LangGraph (ReAct pattern)** to decide when to call a **tool** that fetches **real-time country data** from the **RestCountries API**, then synthesizes an answer using an LLM (**Google Gemini by default**, **Azure OpenAI optional**). Responses are **streamed token-by-token** to the UI, and Streamlit keeps **session chat history**.

- the **UI ↔ agent runtime** boundary,
- the **agent graph + tool invocation loop**,
- the **two external dependencies** (LLM provider + RestCountries),
- and the **configuration/secrets** (.env, optional LangSmith tracing).

Use these directories as your “authoritative components”:

##### Frontend (Streamlit UI)
- `frontend/app.py`
The entrypoint: renders chat UI, maintains conversation in session state, streams outputs.

##### Backend (agent, graph orchestration, tools, prompts, LLM adapters)
- `backend/agents/country_information_agent.py`
Likely where the agent is defined (system behavior, ReAct setup, tool wiring).
- `backend/graph/graph.py`, `backend/graph/state.py`, `backend/graph/invoke.py`
- `backend/tools/tools.py`
The callable tool(s) that hit RestCountries API (HTTP client logic).
- `backend/prompts/country_information_search_prompt.txt`
Prompt template(s) for the agent.
- `backend/llm/google_gemini_ai.py`, `backend/llm/azure_open_ai.py`
Provider adapters; indicate a “pluggable LLM backend” component.
- `backend/utils/utils.py`
Common helpers (formatting, parsing, error handling, etc.).

##### Ops / packaging
- `Dockerfile`, `.devcontainer/*`, `requirements.txt`, `.dockerignore`

##### Streamlit Server (frontend/app.py)
UI + session chat history + streaming renderer
##### Agent Runtime (backend/agents/...)
ReAct agent “brain” (decides tool use vs. direct answer)
##### LangGraph Orchestration (backend/graph/...)
Graph nodes/edges, state transitions, streaming/invocation
##### Tool Layer (backend/tools/tools.py)
“Country search / country info fetch” tool
##### LLM Provider (external)
- Google Gemini (active)
- Azure OpenAI (optional alternate)
##### Prompt Store (backend/prompts/*.txt)
Treated as a dependency feeding the agent/graph
##### Config/Secrets (.env environment variables)
Keys, model selection; optionally LangSmith settings
##### (Optional) LangSmith Tracing (external)
Only if `LANGSMITH_TRACING=true`

##### User → Streamlit UI
- message input event
##### Streamlit UI → Graph Invoke (backend/graph/invoke.py)
- passes user message + session history
##### Graph Invoke → LangGraph (backend/graph/graph.py)
- initializes state (from `backend/graph/state.py`)
##### LangGraph → Agent (backend/agents/country_information_agent.py)
- uses prompt(s)
##### Agent → LLM Adapter (backend/llm/google_gemini_ai.py or azure_open_ai.py) → LLM Provider
- “think/plan/act” step (ReAct)
##### Agent decides
- if **tool needed**: go to tool path (below)
- else answer directly

##### Agent → LLM Provider
- synthesizes final answer grounded in tool output
##### LangGraph → Streamlit UI
- **stream tokens** back
##### Streamlit UI → User
- renders streamed tokens; updates session chat history

##### Observability path (optional)
- **LangGraph/Agent → LangSmith**
- only if tracing enabled

##### ReAct + Tool-use
Call it out visually: “LLM decides to call tool” rather than “tool always called”.
- Use a **decision diamond** or a **conditional edge**: “Need external country data?”

##### Separation of concerns
Even though it’s one repo, the architecture is cleanly layered:
- **Presentation**: Streamlit UI
- **Orchestration**: LangGraph graph + state/invoke
- **Domain agent**: country_information_agent
- **Integrations**: tools (RestCountries), LLM adapters (Gemini/Azure)
- **Configuration**: env vars, model selection by import

##### Pluggable LLM backend
- `GoogleGeminiLLM` (default)
- `AzureOpenAI` (swap by import / config)

##### Streaming UX
That responses are **streamed** from backend to UI. This often gets missed; but it’s a key feature.

##### What to include from deployment (optional but useful)
- **Docker container** running `streamlit run frontend/app.py`
- environment variables from `.env`
- exposed port `8501`
- external network egress to RestCountries + LLM provider (+ LangSmith)

This clarifies runtime boundaries and security considerations (keys never in code).

- Actor: User
- Container: Streamlit App (frontend/app.py)
- Component: Graph Invoke (backend/graph/invoke.py)
- Component: LangGraph Graph (backend/graph/graph.py)
- Component: Graph State (backend/graph/state.py)
- Component: CountryInformationAgent (backend/agents/country_information_agent.py)
- Component: Prompt Template (backend/prompts/country_information_search_prompt.txt)
- Component: Country Info Tool (backend/tools/tools.py)
- Component: LLM Adapter Interface (backend/llm/__init__.py)
- Impl: Google Gemini (backend/llm/google_gemini_ai.py)
- Impl: Azure OpenAI (backend/llm/azure_open_ai.py)
- External: RestCountries API
- External: Google Gemini API / Azure OpenAI API
- External (optional): LangSmith
- Config: .env (GOOGLE_GEMINI_KEY, model, LANGSMITH_*)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Actors
  U["User (Browser)"]:::actor

  %% Presentation
  subgraph "Presentation Layer"
    UI["Streamlit UI & Server\n(chat + session history + streaming)\n(frontend/app.py)"]:::ui
  end

  %% Application / Orchestration
  subgraph "Backend Runtime (Single Python Service)"
    subgraph "Orchestration (LangGraph)"
      INV["Graph Invocation\n(streaming entrypoint)\n(backend/graph/invoke.py)"]:::backend
      STATE["Graph State\n(state shape/container)\n(backend/graph/state.py)"]:::backend
      GRAPH["LangGraph Graph\n(nodes/edges + transitions)\n(backend/graph/graph.py)"]:::backend
    end

    subgraph "Agent & Prompts"
      AGENT["CountryInformationAgent\n(ReAct: plan/act/observe)\n(backend/agents/country_information_agent.py)"]:::backend
      PROMPT["Prompt Template\n(backend/prompts/country_information_search_prompt.txt)"]:::artifact
      UTILS["Shared Utilities\n(format/parse/errors)\n(backend/utils/utils.py)"]:::backend
    end

    subgraph "Integrations"
      TOOL["Tool: RestCountries lookup\n(backend/tools/tools.py)"]:::tool

      subgraph "Pluggable LLM Backend"
        LLMIF["LLM Adapter Interface\n(backend/llm/__init__.py)"]:::backend
        GEM["LLM Adapter: Google Gemini (default)\n(backend/llm/google_gemini_ai.py)"]:::llm
        AZ["LLM Adapter: Azure OpenAI (optional)\n(backend/llm/azure_open_ai.py)"]:::llm
      end
    end

    subgraph "Configuration"
      ENV["Config/Secrets\n.env env vars (keys, model selection,\nLANGSMITH_*)"]:::config
    end
  end

  %% Externals
  subgraph "External Services"
    REST["RestCountries API"]:::external
    GEMAPI["Google Gemini API"]:::external
    AZAPI["Azure OpenAI API"]:::external
    LS["LangSmith Tracing (optional)\n(enabled when LANGSMITH_TRACING=true)"]:::external
  end

  %% Deployment / packaging context (non-runtime logic)
  subgraph "Deployment Context (Packaging)"
    DOCKER["Dockerfile\n(container runtime)"]:::ops
    DEVCONT["Dev Container\n(.devcontainer/devcontainer.json)"]:::ops
    REQS["Python Dependencies\n(requirements.txt)"]:::ops
  end

  %% Primary interaction
  U -->|"message_input"| UI
  UI -->|"call invoke(user_msg,history)"| INV
  INV -->|"init_state"| STATE
  INV -->|"run_graph(state)"| GRAPH
  GRAPH -->|"agent_step"| AGENT

  %% Agent dependencies
  AGENT -->|"load_prompt"| PROMPT
  AGENT -->|"helpers"| UTILS

  %% ReAct: decide tool vs direct answer
  AGENT -->|"select_llm_backend"| LLMIF
  LLMIF -->|"default_impl"| GEM
  LLMIF -->|"optional_impl"| AZ

  GEM -->|"generate(plan/answer)"| GEMAPI
  AZ -->|"generate(plan/answer)"| AZAPI

  %% Conditional tool-use loop
  AGENT -->|"need_country_data?"| DEC{"Tool required?"}:::decision
  DEC -->|"yes:call_tool"| TOOL
  TOOL -->|"HTTP GET"| REST
  REST -->|"country_data"| TOOL
  TOOL -->|"tool_result"| AGENT
  DEC -->|"no:skip_tool"| AGENT

  %% Final synthesis (after tool or direct)
  AGENT -->|"final_answer_tokens"| GRAPH
  GRAPH -.->|"token_stream"| UI
  UI -->|"render_stream + store_history"| U

  %% Optional observability
  GRAPH -.->|"trace_if_enabled"| LS
  AGENT -.->|"trace_if_enabled"| LS

  %% Config wiring
  ENV -->|"API keys + model selection"| GEM
  ENV -->|"API keys + model selection"| AZ
  ENV -.->|"LANGSMITH_*"| LS
  ENV -->|"runtime settings"| UI

  %% Deployment context relationships
  DOCKER -.->|"packages_and_runs"| UI
  REQS -.->|"installs_deps_for"| UI
  REQS -.->|"installs_deps_for"| GRAPH
  DEVCONT -.->|"dev_env_for"| UI

  %% Click events (from component mapping)
  click UI "https://github.com/shaunakbale/country-information-ai-agent/blob/master/frontend/app.py"
  click AGENT "https://github.com/shaunakbale/country-information-ai-agent/blob/master/backend/agents/country_information_agent.py"
  click GRAPH "https://github.com/shaunakbale/country-information-ai-agent/blob/master/backend/graph/graph.py"
  click STATE "https://github.com/shaunakbale/country-information-ai-agent/blob/master/backend/graph/state.py"
  click INV "https://github.com/shaunakbale/country-information-ai-agent/blob/master/backend/graph/invoke.py"
  click TOOL "https://github.com/shaunakbale/country-information-ai-agent/blob/master/backend/tools/tools.py"
  click PROMPT "https://github.com/shaunakbale/country-information-ai-agent/blob/master/backend/prompts/country_information_search_prompt.txt"
  click LLMIF "https://github.com/shaunakbale/country-information-ai-agent/blob/master/backend/llm/__init__.py"
  click GEM "https://github.com/shaunakbale/country-information-ai-agent/blob/master/backend/llm/google_gemini_ai.py"
  click AZ "https://github.com/shaunakbale/country-information-ai-agent/blob/master/backend/llm/azure_open_ai.py"
  click UTILS "https://github.com/shaunakbale/country-information-ai-agent/blob/master/backend/utils/utils.py"
  click DOCKER "https://github.com/shaunakbale/country-information-ai-agent/tree/master/Dockerfile"
  click DEVCONT "https://github.com/shaunakbale/country-information-ai-agent/blob/master/.devcontainer/devcontainer.json"
  click REQS "https://github.com/shaunakbale/country-information-ai-agent/blob/master/requirements.txt"

  %% Styles
  classDef actor fill:#111827,stroke:#374151,color:#F9FAFB,stroke-width:1px
  classDef ui fill:#1D4ED8,stroke:#1E3A8A,color:#FFFFFF,stroke-width:1px
  classDef backend fill:#6B7280,stroke:#374151,color:#FFFFFF,stroke-width:1px
  classDef tool fill:#0F766E,stroke:#134E4A,color:#ECFEFF,stroke-width:1px
  classDef llm fill:#7C3AED,stroke:#4C1D95,color:#F5F3FF,stroke-width:1px
  classDef external fill:#F59E0B,stroke:#92400E,color:#111827,stroke-width:1px
  classDef config fill:#FEF3C7,stroke:#B45309,color:#111827,stroke-width:1px
  classDef artifact fill:#E5E7EB,stroke:#6B7280,color:#111827,stroke-width:1px
  classDef ops fill:#DB2777,stroke:#831843,color:#FFFFFF,stroke-width:1px
  classDef decision fill:#FFFFFF,stroke:#111827,color:#111827,stroke-width:2px
```
