smart-city-digital-twin-martinique/smart-app-city/docs/AI_ARCHITECTURE.md

Smart App City — AI Architecture

Overview

AI-powered features for the Smart App City mobile application, leveraging RAG, LLM, and AI Agents.

AI Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         AI Pipeline                              │
│                                                                  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                     User Query                             │  │
│  │  "Quel est le bus pour Fort-de-France à 14h?"           │  │
│  └───────────────────────┬───────────────────────────────────┘  │
│                          │                                       │
│                          ▼                                       │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                   NLP / Intent Classifier                  │  │
│  │  - Intent: transport.search                               │  │
│  │  - Entities: {time: "14h", destination: "Fort-de-France"}│  │
│  │  - Language: fr                                           │  │
│  └───────────────────────┬───────────────────────────────────┘  │
│                          │                                       │
│              ┌───────────┼───────────┐                          │
│              ▼           ▼           ▼                          │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐           │
│  │ Transport    │ │ Tourisme     │ │ Services     │           │
│  │ Agent        │ │ Agent        │ │ Agent        │           │
│  └──────┬───────┘ └──────┬───────┘ └──────┬───────┘           │
│         │                │                │                     │
│         └────────────────┴────────────────┘                     │
│                          │                                       │
│                          ▼                                       │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                      RAG Pipeline                          │  │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐    │  │
│  │  │ Query    │ │ Embed    │ │ Vector   │ │ Rerank   │    │  │
│  │  │ Rewrite  │ │ (E5)     │ │ Search   │ │ (BM25+)  │    │  │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘    │  │
│  └───────────────────────┬───────────────────────────────────┘  │
│                          │                                       │
│                          ▼                                       │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                   LLM Generation                           │  │
│  │  - Context: Retrieved documents + real-time data           │  │
│  │  - Model: Llama 3.1 70B (LocalAI)                        │  │
│  │  - Output: Natural language response                       │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Components

1. LocalAI (LLM Server)

• Container: localai-api (existing)
• Model: Llama 3.1 70B quantized or Mistral 7B
• API: OpenAI-compatible (/v1/completions, /v1/chat/completions)
• Endpoint: http://localai-api:8080

2. RAG Pipeline

Embedding

• Model: intfloat/multilingual-e5-large (multilingual)
• Dimensions: 1024
• Input: Documents, FAQ, municipal data, tourist guides

Vector Database

• Engine: Qdrant (existing)
• Collection: smart-city-docs
• Payload: {doc_type, language, timestamp, source}

Documents to Index

Source	Type	Language
Municipal regulations	PDF/HTML	FR, EN
Tourist guides	Markdown	FR, EN, ES, DE
Transport schedules	JSON/API	FR
FAQ	Markdown	FR, EN, ES, DE
Event calendar	API	FR
Sensor data descriptions	JSON	FR, EN

3. AI Agents

Transport Agent

• Tools: Bus API, Parking API, Traffic API
• Capabilities: Schedule lookup, route planning, real-time delays
• Data Sources: FROST-Server, Orion-LD

Tourism Agent

• Tools: POI database, Weather API, Event API
• Capabilities: Recommendations, itineraries, booking suggestions
• Data Sources: PostGIS (POI), OpenWeatherMap

Services Agent

• Tools: Forms API, Appointment API, Document API
• Capabilities: Procedure guidance, appointment scheduling
• Data Sources: City ERP

Environment Agent

• Tools: Sensor API, Air Quality API, Weather API
• Capabilities: Real-time monitoring, health recommendations
• Data Sources: InfluxDB (IoT sensors)

Implementation

RAG Service (Python/FastAPI)

# ai/rag-service/main.py
from fastapi import FastAPI
from langchain import hub
from langchain_community.embeddings import HuggingFaceEmbeddings
from langchain_community.vectorstores import Qdrant
from langchain_community.llms import OpenAI

app = FastAPI()

# Connect to LocalAI
llm = OpenAI(
    base_url="http://localai-api:8080/v1",
    api_key="dummy",
    model="llama-3.1-70b"
)

# Connect to Qdrant
embeddings = HuggingFaceEmbeddings(
    model_name="intfloat/multilingual-e5-large"
)
vectorstore = Qdrant.from_existing_collection(
    collection_name="smart-city-docs",
    embedding=embeddings,
    url="http://qdrant:6333"
)

@app.post("/query")
async def query(request: QueryRequest):
    # Vector search
    docs = vectorstore.similarity_search(request.query, k=5)
    
    # RAG prompt
    prompt = hub.pull("rlm/rag-prompt")
    chain = prompt | llm | StrParser()
    
    response = chain.invoke({
        "question": request.query,
        "context": format_docs(docs)
    })
    
    return {"response": response, "sources": [d.metadata for d in docs]}

Agent Service (Python/LangChain)

# ai/agent-service/agents/transport.py
from langchain.agents import AgentExecutor, create_openai_functions_agent
from langchain_community.tools import Tool

tools = [
    Tool(
        name="bus_schedule",
        func=bus_schedule_lookup,
        description="Lookup bus schedules. Input: route_id, time"
    ),
    Tool(
        name="parking_availability",
        func=parking_lookup,
        description="Check parking availability. Input: location, time"
    ),
    Tool(
        name="traffic_conditions",
        func=traffic_lookup,
        description="Get traffic conditions. Input: route, time"
    )
]

agent = create_openai_functions_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools)

Multilingual Support

LLM Prompts per Language

# ai/agent-service/prompts/fr.yml
transport_agent: |
  Tu es un assistant transport pour la Martinique.
  Réponds en français de manière concise et utile.
  Donne les horaires de bus, places de parking, et conditions de circulation.

# ai/agent-service/prompts/en.yml
transport_agent: |
  You are a transport assistant for Martinique.
  Respond in English concisely and helpfully.
  Provide bus schedules, parking availability, and traffic conditions.

Translation Fallback

For languages without specific prompts, use automatic translation:

1. Detect language → translate query to FR/EN
2. Process in FR/EN
3. Translate response back to original language

Roadmap

Phase 1: RAG Setup

• Deploy Qdrant collection
• Index municipal documents
• Connect LocalAI
• Basic Q&A endpoint

Phase 2: AI Agents

• Transport agent
• Tourism agent
• Services agent
• Environment agent

Phase 3: Advanced Features

• Multi-turn conversations
• Personalization
• Predictive recommendations
• Voice interface (STT/TTS)