Apppublic

jfrometa88/refugeeconnect-ai-api

sourceHugging Facemitupdated 5mo agoView on Hugging Face

0likes

App README

RefugeeConnect AI — Backend API 🧠

The intelligence layer of RefugeeConnect AI — a multi-agent system helping migrants and asylum seekers navigate the support system in Spain.

This Space is the AI backend of RefugeeConnect AI. It processes natural language requests in Spanish, English, Arabic, and French, and returns personalized, step-by-step guidance toward the right resources — legal aid, healthcare, housing, food, and employment.

The visual interface lives here: jfrometa88/refugeeconnect-ai-dashboard

🤖 Agent Architecture

The backend is built with Google's Agent Development Kit (ADK) around a single Orchestrator Agent operating on a 5-state decision tree:

1: Greet & detect language
2: Understand user's legal profile (Padrón, Tarjeta Roja, etc.)
3: Clarify if the query is incomplete
4: Call the appropriate tool (search_db, legal_rights, geolocate)
5: Respond and stop

Key design decisions:

—Tools — not the model — hold all legal information: static, human-verified, zero hallucination risk
—Explicit stop markers prevent verbosity and loop behavior in smaller models
—All system logic is written in English; all user-facing content is delivered in the user's detected language

📡 Endpoints

Endpoint	Description
`GET /health`	System status and model availability
`POST /query`	Main conversational endpoint — accepts user message and session context
`GET /logs`	Last n (default 50) lines of system logs
`GET /docs`	Interactive Swagger documentation

🏗️ Technology Stack

Layer	Technology
Agent Framework	Google ADK (Agent Development Kit)
Routing & Distances	OSRM (Open Source Routing Machine) via router.project-osrm.org
Model	Gemma 4 (31B) via Google AI Studio
API Framework	FastAPI (async)
Database	SQLite — initialized from CSV sources at container startup
Dependency Manager	`uv`
Container	Docker on Python 3.13-slim

⚙️ Environment Variables

Variable	Description	Default
`GOOGLE_API_KEY`	Google AI Studio API key	— (required Secret)
`USE_LOCAL_LLM`	Switch to local Ollama inference	`false`
`GEMMA_MODEL_NAME_cloud`	Cloud model identifier	`gemma-4-31b-it`
`OLLAMA_HOST`	Ollama server URL (local mode only)	`http://localhost:11434`
`GEMMA_MODEL_NAME_local`	Local model identifier (local mode only)	`gemma-4`

GOOGLE_API_KEY must be set. USE_LOCAL_LLM=true is designed for NGO on-premise deployments via Ollama, not for this hosted Space.

🔒 Privacy Design

For organizations handling sensitive personal data, the full system supports a local-first inference mode using Gemma 4 via Ollama (E2B/E4B models). In that configuration, no user data leaves the organization's own infrastructure.

This hosted Space runs in cloud mode for demonstration purposes. The local mode is documented and functional for on-premise deployment.

📌 Current Scope

The database currently covers a representative sample of NGO resources in Valencia, Spain. The architecture scales horizontally — expanding to any city requires only populating the database with new records.

🔗 Project Links

—🗺️ Dashboard: jfrometa88/refugeeconnect-ai-dashboard
—📂 GitHub Repository: (https://github.com/jfrometa88/RefugeeConnect)

👤 Author

Jorge Israel Frometa Moya — Cuban Engineer & Political Asylum Seeker in Spain.

This project was born from personal experience navigating a fragmented support system. Built with limited resources, submitted with the hope it reaches those who can take it further.

Submitted to the Gemma 4 Good Hackathon — Impact Track: Digital Equity & Inclusivity · Special Track: Ollama