How akramiot/agentic-hospitality-concierge works
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: main.py Main agent · state.py State machine · store.py Storage · synthesis.py Synthesis
Components 29
Core agent
Request orchestration, state, synthesis, and model/provider abstractions.
- Main agent · Primary entrypoint that routes requests through the concierge pipeline.
app/main.py - State machine · Explicit control flow for clarify, plan, execute, validate, retry, and synthesize.
app/state.py - Agent pipeline · Composition layer for the agent runtime and execution steps.
app/agent/pipeline.py - LLM provider · Abstraction over local and Azure chat model backends.
app/providers/llm.py - Embedding provider · Abstraction for embedding generation used by retrieval.
app/providers/embeddings.py - Trip schema · Structured response models, especially TripPlan.
app/models.py - Synthesis · Combines tool results into validated structured plans.
app/synthesis.py - Weather tool · Weather lookup integration used by the agent.
app/tools/weather.py - FX tool · Currency conversion and exchange-rate lookup.
app/tools/fx.py - Search tool · Web search integration for destination and local discovery.
app/tools/search.py - Card tool · Rules-based recommendation for payment card guidance.
app/tools/card.py - Knowledge tool · Retrieval-backed tool for hospitality knowledge and snippets.
app/tools/knowledge.py - Calendar tool · Scheduling and itinerary timing support.
app/tools/calendar.py - Translation tool · Language translation support for guest interactions.
app/tools/translation.py
Data layer
Memory, storage, retrieval, and durable knowledge artifacts.
- Session memory · In-session context and tool traces for the active conversation.
app/memory.py - Long-term memory · Persistent guest and query history across sessions.
app/long_term_memory.py - Storage · Backs memory and artifacts with local files or Cosmos DB.
app/storage/store.py - Local store · Default JSON-backed storage for local-first deployment.
app/storage/local_store.py - RAG ingest · Builds searchable knowledge snippets and embeddings.
app/rag/ingest.py - Retriever · Cosine-similarity retrieval over stored knowledge snippets.
app/rag/retriever.py - Knowledge base · Domain-specific knowledge helpers shared by retrieval and tools.
app/knowledge_base.py
User interfaces
CLI, Streamlit, and lobby-facing presentation layers.
- CLI chat · Command-line entrypoint for conversational use.
chat.py - Streamlit app · Primary interactive UI shell for the concierge experience.
streamlit_app.py - Lobby app · Reception-oriented application wrapper for the Rosewood flow.
lobby_app.py - Lobby package · Guest-facing concierge, personalization, maps, services, and voice layers.
app/lobby/concierge.py - Voice layer · Optional speech generation and briefing support.
app/voice/tts_service.py
Ops and quality
Evaluation, ingestion, and runtime checks around the main app.
- Evaluation · LLM-as-judge scoring and correction support.
app/eval/judge.py - System check · Runtime readiness and environment validation.
app/scripts/system_check.py - Ingest scripts · Knowledge ingestion and readiness scripts for the local stack.
scripts/ingest_knowledge.py
Connections 28
- 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.