# akramiot/agentic-hospitality-concierge architecture

> Architecture diagram of the GitHub repository akramiot/agentic-hospitality-concierge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akramiot/agentic-hospitality-concierge
- Repository: https://github.com/akramiot/agentic-hospitality-concierge

## Overview

1. **Overall shape**
   This repo is a local-first hospitality concierge built around a custom Python agent runtime. The core job is to turn a guest’s natural-language request into a structured `TripPlan` by orchestrating tools, memory, retrieval, and synthesis. The same codebase can run fully on laptop/local stack or switch to Azure-backed services through `DEPLOYMENT_MODE`.

2. **Main orchestration boundary**
   `app/main.py` is the primary agent entrypoint and request pipeline. It sits above the state machine in `app/state.py`, the LLM clients in `app/providers/`, and the tool modules in `app/tools/`. This is the central boundary to show in a diagram: user input enters the orchestrator, which decides whether to clarify, call tools, validate, retry, or synthesize output.

3. **Agent control flow**
   The agent follows an explicit state machine rather than a framework-managed loop. The phases are clarify requirements, plan tools, execute tools, validate results, handle errors/retries, and synthesize. This matters architecturally because tool invocation and recovery are deterministic and visible in code, not hidden in an external SDK.

4. **Tool layer**
   The concierge’s domain logic is split into seven tool modules under `app/tools/`: weather, FX, search, card, knowledge, calendar, and translation. These are plain Python components invoked directly by the orchestrator. Some tools call external APIs, while others are in-process rules or local mocks, so they form the main “execution” tier of the system.

5. **External service dependencies**
   The local deployment uses Open-Meteo for weather, Frankfurter for FX, and DuckDuckGo for search. Card recommendations are handled by an internal rules engine. Translation and search can be upgraded in Azure mode. These services are not uniformly required; only the weather/FX/search tools are hard external integrations in the local path.

6. **Memory architecture**
   Memory is split into short-term and long-term layers. `app/memory.py` manages in-session context and tool traces, while `app/long_term_memory.py` persists durable guest/query history. The persistence boundary is implemented through `app/storage/`, which abstracts local JSON files versus Cosmos DB. This is a distinct subsystem from RAG knowledge storage even though both can use the same local data directory.

7. **RAG and knowledge base**
   Retrieval is handled by `app/rag/ingest.py` and `app/rag/retriever.py`, with domain helpers in `app/knowledge_base.py` and a knowledge-focused tool in `app/tools/knowledge.py`. The readme indicates embeddings + cosine similarity over snippets, stored locally in JSON by default and optionally in Cosmos. In diagrams, this should be shown as a retrieval subsystem feeding the agent, separate from conversational memory.

8. **Model/provider abstraction**
   `app/providers/llm.py` and `app/providers/embeddings.py` abstract model access. In local mode they target Ollama via OpenAI-compatible APIs; in Azure mode they use Azure OpenAI. This abstraction is a major architectural seam because the rest of the app depends on a provider interface rather than a vendor-specific SDK.

9. **Structured output and synthesis**
   `app/models.py` defines the typed output schema, especially `TripPlan`, and `app/synthesis.py` merges tool results into that schema. The agent is therefore not just generating text; it is assembling validated JSON with destination, weather, search results, citations, card advice, currency info, and next steps. For architecture diagrams, this is the “output shaping” stage after tool aggregation.

10. **Hospitality UI surfaces**
    There are multiple front ends, all wrapping the same underlying concierge logic: `chat.py` for CLI chat, `streamlit_app.py` for the general UI, and `lobby_app.py` plus the `app/lobby/` package for the Rosewood reception experience. The Streamlit pages under `pages/` add specialized experiences such as visitor map/geofencing, services, management insights, and booking. These are presentation-layer boundaries, not separate business logic stacks.

11. **Voice and personalization path**
    Voice support is isolated in `app/voice/` and the lobby-specific modules such as `app/lobby/personalized_voice.py` and `app/lobby/voice_briefing.py`. The repo already includes an ElevenLabs client and TTS service, but the README positions voice as an optional/enhanced path layered on top of the same concierge planning flow. This should be drawn as an additional output channel, not as the core agent.

12. **Evaluation, scripts, and operational support**
    `app/eval/` contains LLM-as-judge evaluation, useful for scoring responses and generating correction hints. Ingestion and runtime checks are handled by scripts such as `scripts/ingest_knowledge.py`, `scripts/verify_ready.py`, and `app/scripts/system_check.py`. These are supporting pipelines around the main app, not part of user-facing request handling.

13. **Persistence and local artifacts**
    The default runtime writes to `data/local/` for knowledge and memory JSON. That local artifact store is the main durable state in local mode and should be shown as a file-based persistence layer. In Azure mode, the same logical roles map to Cosmos DB and Azure OpenAI, but the application structure stays the same.

14. **Testing boundary**
    The `tests/` suite covers memory, state, booking store, geofence, personalized voice, TTS, models, tools, and integration behavior. This indicates the repo is organized around stable module boundaries rather than one monolithic app. For an architecture diagram, the test layer can be shown as cross-cutting validation over agent, storage, tools, and UI components.

Main entry points: [`app/main.py`](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/main.py) (Main agent), [`app/state.py`](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/state.py) (State machine), [`app/storage/store.py`](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/storage/store.py) (Storage), [`app/synthesis.py`](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/synthesis.py) (Synthesis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core agent"]
  node_main["Main agent<br/>orchestrator<br/>[main.py]"]
  node_state["State machine<br/>agent state<br/>[state.py]"]
  node_pipeline["Agent pipeline<br/>[pipeline.py]"]
  node_llm["LLM provider<br/>model adapter<br/>[llm.py]"]
  node_embeddings["Embedding provider<br/>model adapter<br/>[embeddings.py]"]
  node_models["Trip schema<br/>typed output<br/>[models.py]"]
  node_synthesis["Synthesis<br/>output assembler<br/>[synthesis.py]"]
  node_weather["Weather tool<br/>[weather.py]"]
  node_fx["FX tool<br/>[fx.py]"]
  node_search["Search tool<br/>[search.py]"]
  node_card["Card tool<br/>[card.py]"]
  node_knowledge_tool["Knowledge tool<br/>[knowledge.py]"]
  node_calendar["Calendar tool<br/>[calendar.py]"]
  node_translation["Translation tool<br/>[translation.py]"]
end

subgraph group_data["Data layer"]
  node_memory[("Session memory<br/>short-term memory<br/>[memory.py]")]
  node_longterm[("Long-term memory<br/>durable memory")]
  node_store[("Storage<br/>persistence abstraction<br/>[store.py]")]
  node_localstore[("Local store<br/>file persistence<br/>[local_store.py]")]
  node_rag_ingest["RAG ingest<br/>ingestion<br/>[ingest.py]"]
  node_rag_retriever["Retriever<br/>retrieval<br/>[retriever.py]"]
  node_knowledge_base["Knowledge base<br/>domain knowledge<br/>[knowledge_base.py]"]
end

subgraph group_ui["User interfaces"]
  node_chat_cli["CLI chat<br/>cli frontend<br/>[chat.py]"]
  node_streamlit["Streamlit app<br/>web frontend<br/>[streamlit_app.py]"]
  node_lobby_app["Lobby app<br/>lobby frontend<br/>[lobby_app.py]"]
  node_lobby_pkg["Lobby package<br/>lobby modules<br/>[concierge.py]"]
  node_voice["Voice layer<br/>audio output<br/>[tts_service.py]"]
end

subgraph group_ops["Ops and quality"]
  node_eval["Evaluation<br/>quality pipeline<br/>[judge.py]"]
  node_system_check["System check<br/>ops check<br/>[system_check.py]"]
  node_ingest_script["Ingest scripts<br/>ops script"]
end

node_main -->|"drives"| node_state
node_main -->|"uses"| node_pipeline
node_main -->|"queries"| node_llm
node_main -->|"reads/writes"| node_memory
node_main -->|"assembles"| node_synthesis
node_state -->|"invokes"| node_weather
node_state -->|"invokes"| node_fx
node_state -->|"invokes"| node_search
node_state -->|"invokes"| node_card
node_state -->|"invokes"| node_knowledge_tool
node_state -->|"invokes"| node_calendar
node_state -->|"invokes"| node_translation
node_weather -.->|"augments"| node_search
node_knowledge_tool -->|"retrieves"| node_rag_retriever
node_rag_ingest -->|"builds"| node_embeddings
node_rag_retriever -->|"queries"| node_knowledge_base
node_memory -->|"persists"| node_store
node_longterm -->|"persists"| node_store
node_store -->|"defaults to"| node_localstore
node_synthesis -->|"fills"| node_models
node_chat_cli -->|"enters"| node_main
node_streamlit -->|"enters"| node_main
node_lobby_app -->|"wraps"| node_lobby_pkg
node_lobby_pkg -->|"reuses"| node_main
node_voice -.->|"extends"| node_main
node_eval -.->|"scores"| node_main
node_system_check -.->|"verifies"| node_store
node_ingest_script -->|"runs"| node_rag_ingest

click node_main "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/main.py"
click node_state "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/state.py"
click node_pipeline "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/agent/pipeline.py"
click node_llm "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/providers/llm.py"
click node_embeddings "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/providers/embeddings.py"
click node_models "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/models.py"
click node_synthesis "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/synthesis.py"
click node_memory "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/memory.py"
click node_longterm "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/long_term_memory.py"
click node_store "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/storage/store.py"
click node_localstore "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/storage/local_store.py"
click node_rag_ingest "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/rag/ingest.py"
click node_rag_retriever "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/rag/retriever.py"
click node_knowledge_base "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/knowledge_base.py"
click node_weather "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/tools/weather.py"
click node_fx "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/tools/fx.py"
click node_search "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/tools/search.py"
click node_card "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/tools/card.py"
click node_knowledge_tool "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/tools/knowledge.py"
click node_calendar "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/tools/calendar.py"
click node_translation "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/tools/translation.py"
click node_chat_cli "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/chat.py"
click node_streamlit "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/streamlit_app.py"
click node_lobby_app "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/lobby_app.py"
click node_lobby_pkg "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/lobby/concierge.py"
click node_voice "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/voice/tts_service.py"
click node_eval "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/eval/judge.py"
click node_system_check "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/scripts/system_check.py"
click node_ingest_script "https://github.com/akramiot/agentic-hospitality-concierge/blob/main/scripts/ingest_knowledge.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_state,node_pipeline,node_llm,node_embeddings,node_models,node_synthesis,node_weather,node_fx,node_search,node_card,node_knowledge_tool,node_calendar,node_translation toneBlue
class node_memory,node_longterm,node_store,node_localstore,node_rag_ingest,node_rag_retriever,node_knowledge_base toneAmber
class node_chat_cli,node_streamlit,node_lobby_app,node_lobby_pkg,node_voice toneMint
class node_eval,node_system_check,node_ingest_script toneRose
```

## Components

### Core agent

Request orchestration, state, synthesis, and model/provider abstractions.

- [Main agent](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/main.py): orchestrator · Primary entrypoint that routes requests through the concierge pipeline. · `app/main.py`
- [State machine](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/state.py): agent state · Explicit control flow for clarify, plan, execute, validate, retry, and synthesize. · `app/state.py`
- [Agent pipeline](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/agent/pipeline.py): pipeline · Composition layer for the agent runtime and execution steps. · `app/agent/pipeline.py`
- [LLM provider](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/providers/llm.py): model adapter · Abstraction over local and Azure chat model backends. · `app/providers/llm.py`
- [Embedding provider](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/providers/embeddings.py): model adapter · Abstraction for embedding generation used by retrieval. · `app/providers/embeddings.py`
- [Trip schema](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/models.py): typed output · Structured response models, especially TripPlan. · `app/models.py`
- [Synthesis](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/synthesis.py): output assembler · Combines tool results into validated structured plans. · `app/synthesis.py`
- [Weather tool](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/tools/weather.py): tool · Weather lookup integration used by the agent. · `app/tools/weather.py`
- [FX tool](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/tools/fx.py): tool · Currency conversion and exchange-rate lookup. · `app/tools/fx.py`
- [Search tool](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/tools/search.py): tool · Web search integration for destination and local discovery. · `app/tools/search.py`
- [Card tool](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/tools/card.py): tool · Rules-based recommendation for payment card guidance. · `app/tools/card.py`
- [Knowledge tool](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/tools/knowledge.py): tool · Retrieval-backed tool for hospitality knowledge and snippets. · `app/tools/knowledge.py`
- [Calendar tool](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/tools/calendar.py): tool · Scheduling and itinerary timing support. · `app/tools/calendar.py`
- [Translation tool](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/tools/translation.py): tool · Language translation support for guest interactions. · `app/tools/translation.py`

### Data layer

Memory, storage, retrieval, and durable knowledge artifacts.

- [Session memory](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/memory.py): short-term memory · In-session context and tool traces for the active conversation. · `app/memory.py`
- [Long-term memory](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/long_term_memory.py): durable memory · Persistent guest and query history across sessions. · `app/long_term_memory.py`
- [Storage](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/storage/store.py): persistence abstraction · Backs memory and artifacts with local files or Cosmos DB. · `app/storage/store.py`
- [Local store](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/storage/local_store.py): file persistence · Default JSON-backed storage for local-first deployment. · `app/storage/local_store.py`
- [RAG ingest](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/rag/ingest.py): ingestion · Builds searchable knowledge snippets and embeddings. · `app/rag/ingest.py`
- [Retriever](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/rag/retriever.py): retrieval · Cosine-similarity retrieval over stored knowledge snippets. · `app/rag/retriever.py`
- [Knowledge base](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/knowledge_base.py): domain knowledge · Domain-specific knowledge helpers shared by retrieval and tools. · `app/knowledge_base.py`

### User interfaces

CLI, Streamlit, and lobby-facing presentation layers.

- [CLI chat](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/chat.py): cli frontend · Command-line entrypoint for conversational use. · `chat.py`
- [Streamlit app](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/streamlit_app.py): web frontend · Primary interactive UI shell for the concierge experience. · `streamlit_app.py`
- [Lobby app](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/lobby_app.py): lobby frontend · Reception-oriented application wrapper for the Rosewood flow. · `lobby_app.py`
- [Lobby package](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/lobby/concierge.py): lobby modules · Guest-facing concierge, personalization, maps, services, and voice layers. · `app/lobby/concierge.py`
- [Voice layer](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/voice/tts_service.py): audio output · Optional speech generation and briefing support. · `app/voice/tts_service.py`

### Ops and quality

Evaluation, ingestion, and runtime checks around the main app.

- [Evaluation](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/eval/judge.py): quality pipeline · LLM-as-judge scoring and correction support. · `app/eval/judge.py`
- [System check](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/app/scripts/system_check.py): ops check · Runtime readiness and environment validation. · `app/scripts/system_check.py`
- [Ingest scripts](https://github.com/akramiot/agentic-hospitality-concierge/blob/main/scripts/ingest_knowledge.py): ops script · Knowledge ingestion and readiness scripts for the local stack. · `scripts/ingest_knowledge.py`

## Connections

- Main agent → State machine: drives · Main entrypoint advances requests through the explicit state machine.
- Main agent → Agent pipeline: uses · Agent runtime is composed through the pipeline layer.
- Main agent → LLM provider: queries · Orchestrator calls the model provider for planning and synthesis decisions.
- Main agent → Session memory: reads/writes · Conversation context and tool traces are maintained in session memory.
- Main agent → Synthesis: assembles · Final responses are shaped into structured trip plans.
- State machine → Weather tool: invokes · State machine schedules tool execution as part of the agent flow.
- State machine → FX tool: invokes · State machine schedules tool execution as part of the agent flow.
- State machine → Search tool: invokes · State machine schedules tool execution as part of the agent flow.
- State machine → Card tool: invokes · State machine schedules tool execution as part of the agent flow.
- State machine → Knowledge tool: invokes · State machine schedules tool execution as part of the agent flow.
- State machine → Calendar tool: invokes · State machine schedules tool execution as part of the agent flow.
- State machine → Translation tool: invokes · State machine schedules tool execution as part of the agent flow.
- Weather tool → Search tool: augments · Destination context can combine weather and search signals.
- Knowledge tool → Retriever: retrieves · Knowledge tool delegates to retrieval over stored snippets.
- RAG ingest → Embedding provider: builds · Ingestion generates embeddings for knowledge snippets.
- Retriever → Knowledge base: queries · Retriever uses domain knowledge content as its corpus.
- Session memory → Storage: persists · Session memory is backed by the storage abstraction.
- Long-term memory → Storage: persists · Durable memory uses the same storage boundary.
- Storage → Local store: defaults to · Local-first runtime stores artifacts as JSON on disk.
- Synthesis → Trip schema: fills · Synthesizer produces the typed TripPlan schema.
- CLI chat → Main agent: enters · CLI chat forwards user requests to the agent runtime.
- Streamlit app → Main agent: enters · General Streamlit UI forwards user requests to the agent runtime.
- Lobby app → Lobby package: wraps · Lobby application composes Rosewood-specific presentation modules.
- Lobby package → Main agent: reuses · Lobby experiences reuse the same concierge planning flow.
- Voice layer → Main agent: extends · Voice is an optional output channel layered on top of the core agent.
- Evaluation → Main agent: scores · Evaluation checks agent behavior and response quality.
- System check → Storage: verifies · Readiness checks inspect persistence and environment wiring.
- Ingest scripts → RAG ingest: runs · Scripts trigger knowledge ingestion pipelines.
