Educational demonstration of how modern LLMs orchestrate specialized agents to answer complex queries
WikidAI is an educational proof-of-concept that demonstrates how Large Language Models can orchestrate multiple specialized agents to answer complex questions. Unlike black-box AI assistants, WikidAI shows you exactly how it thinks - you can watch in real-time as it:
- 🧠 Reasons about which data sources to query
- 🔧 Generates SPARQL queries for Wikidata's knowledge graph
- 🌐 Fetches summaries from Wikipedia and OpenStreetMap
- ⛅ Retrieves real-time weather data
- 🔄 Chains multiple queries together to answer complex questions
I have built it in a few hours for a short lightning talk for itWikiCon 2025 on November 8, 2025 in Catania. This Proof of Concept showcases the power of transparent AI orchestration with Gemini 2.5 Pro.
Get WikidAI running in under 2 minutes:
- 🐳 Docker and Docker Compose installed
- 🔑 Gemini API key (Get it free from Google AI Studio)
# 1. Clone the repository
git clone https://github.com/gnovelli/wikidai.git
cd wikidai
# 2. Configure your API key
cd backend
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY
# 3. Launch with Docker
cd ..
docker compose upOpen your browser and navigate to:
- 🖥️ Dashboard: http://localhost:8080
- 🔌 API: http://localhost:3000
- 💚 Health Check: http://localhost:3000/health
Unlike typical AI assistants that hide their decision-making process, WikidAI provides a real-time window into the AI's thoughts:
User: "Who is the mayor of Rome and what's the weather there?"
AI Reasoning (visible to you):
├─ 🤔 Need to find current mayor → Query Wikidata with SPARQL
├─ 📍 Got Roberto Gualtieri → Need location coordinates
├─ 🗺️ Query Nominatim for Rome coordinates
└─ ⛅ Query OpenMeteo for current weather
Final Answer: "Roberto Gualtieri is the mayor of Rome.
Current weather: 22°C, partly cloudy..."
| Feature | Description |
|---|---|
| 🛡️ SPARQL Gauntlet | Multi-layer security validation for generated queries |
| 🧪 Syntax Validation | Uses sparqljs to validate queries before execution |
| 💬 Multi-Turn Conversations | Maintains context across multiple questions |
| ⚡ Function Calling | Native Gemini 2.5 Pro function orchestration |
| 🎨 Educational UI | 3-panel dashboard showing Input → Reasoning → Output |
| 🐳 Docker-First | Zero-config deployment with hot-reload for development |
-
WikidataAgent - Queries the world's largest open knowledge graph
- Generates SPARQL queries from natural language
- Handles entity disambiguation (e.g., "Paris the city" vs "Paris Hilton")
- Validates and sanitizes all queries
-
WikipediaAgent - Fetches concise summaries
- Multi-language support
- Fallback handling for missing articles
-
NominatimAgent - Geocoding and reverse geocoding
- Powered by OpenStreetMap data
- Returns detailed location information
-
OpenMeteoAgent - Real-time weather data
- No API key required
- Current conditions and forecasts
💬 "Who was Albert Einstein?"
→ Fetches Wikipedia summary
💬 "What's the population of Tokyo?"
→ Generates and executes SPARQL query on Wikidata
💬 "Who is the mayor of Rome and what's the weather there today?"
→ Chains: Wikidata → Nominatim → OpenMeteo
💬 "Tell me about Marie Curie and the weather in her birthplace"
→ Chains: Wikipedia → Wikidata → Nominatim → OpenMeteo
💬 "List all Italian cities with more than 500,000 inhabitants"
→ Generates complex SPARQL with filters and aggregations
💬 "Who are the Nobel Prize winners born in Germany?"
→ Demonstrates entity disambiguation and property navigation
WikidAI uses a clean, layered architecture designed for educational clarity:
┌─────────────────────────────────────────────────────┐
│ 🌐 User Browser │
│ http://localhost:8080 │
└────────────────────┬────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 📱 Frontend (Nginx + Vanilla JS) │
│ • 3-Panel Dashboard (Input/Reasoning/Output) │
│ • Real-time thought stream visualization │
│ • Agent call tracking & metrics │
└────────────────────┬────────────────────────────────┘
│ REST API
▼
┌─────────────────────────────────────────────────────┐
│ 🎯 Backend (Express + TypeScript) │
│ │
│ ┌──────────────────────────────────────────┐ │
│ │ 🧠 Gemini Orchestrator │ │
│ │ (Function Calling + Thinking Mode) │ │
│ └──────────┬───────────────────────────────┘ │
│ │ │
│ ┌────────┴────────┬──────────┬─────────┐ │
│ ▼ ▼ ▼ ▼ │
│ ┌────┐ ┌────┐ ┌────┐ ┌────┐ │
│ │ 📚 │ │ 🗺️ │ │ 🌍 │ │ ⛅ │ │
│ │Wiki│ │Nom │ │Wiki│ │Open│ │
│ │data│ │inat│ │pedi│ │Mete│ │
│ │ │ │im │ │a │ │o │ │
│ └────┘ └────┘ └────┘ └────┘ │
│ │
└──────────────┬──────────────────────────────────────┘
│
▼
┌──────────────────┐
│ 💾 Redis Cache │
│ (Future: Rate │
│ Limiting) │
└──────────────────┘
External APIs:
├─ Wikidata SPARQL Endpoint (query.wikidata.org)
├─ Wikipedia API (en.wikipedia.org/api)
├─ Nominatim (nominatim.openstreetmap.org)
├─ OpenMeteo (api.open-meteo.com)
└─ Gemini 2.5 Pro (generativelanguage.googleapis.com)
🎨 Why Vanilla JS for Frontend?
- Educational clarity - no framework magic to understand
- Fast iteration during PoC phase
- Easy for contributors to jump in
🤖 Why Gemini 2.5 Pro?
- Native function calling (no custom parsing needed)
- "Thinking mode" for transparent reasoning
- Extended context window (1M tokens)
- Cost-effective for educational projects
🐳 Why Docker-First?
- Zero dependency conflicts
- Identical dev/prod environments
- Hot-reload for rapid development
wikidai/
├── 🎨 frontend/
│ ├── index.html # 3-panel dashboard UI
│ ├── nginx.conf # Reverse proxy config
│ └── Dockerfile # Nginx container
│
├── ⚙️ backend/
│ ├── src/
│ │ ├── 🤖 agents/
│ │ │ ├── wikidata-agent.ts # SPARQL generation & validation
│ │ │ ├── wikipedia-agent.ts # Wikipedia API wrapper
│ │ │ ├── nominatim-agent.ts # Geocoding service
│ │ │ └── openmeteo-agent.ts # Weather data
│ │ │
│ │ ├── 📝 prompts/
│ │ │ ├── system-instructions.ts # Balanced mode
│ │ │ └── wikidata-focused-instructions.ts # SPARQL-first mode
│ │ │
│ │ ├── orchestrator.ts # Gemini function calling logic
│ │ ├── conversation-manager.ts # Multi-turn state management
│ │ ├── reflexive-mode.ts # Advanced reasoning loops
│ │ ├── config.ts # Environment configuration
│ │ ├── types.ts # TypeScript interfaces
│ │ └── index.ts # Express server
│ │
│ ├── Dockerfile # Multi-stage Node.js build
│ ├── package.json
│ └── tsconfig.json
│
├── 🐳 docker-compose.yml # Full stack orchestration
├── 📖 README.md #
# Inside Docker container
docker compose exec backend npm test
# Or locally (requires Node.js 20+)
cd backend
npm install
npm test# Start all services with hot-reload
docker compose up
# Rebuild after Dockerfile changes
docker compose up --build
# View logs in real-time
docker compose logs -f backend
# Stop all services
docker compose down
# Stop and remove volumes (clean slate)
docker compose down -v
# Run a specific agent test
docker compose exec backend npm run test:wikidataCreate backend/.env with:
# Required
GEMINI_API_KEY=your_api_key_here
# Optional
NODE_ENV=development
PORT=3000
REDIS_URL=redis://redis:6379
LOG_LEVEL=debug| Feature | Status | Details |
|---|---|---|
| Docker Setup | ✅ Complete | Multi-stage builds, hot-reload, health checks |
| Gemini Integration | ✅ Complete | Function calling, thinking mode, history |
| Wikidata Agent | ✅ Complete | SPARQL generation, validation, gauntlet |
| Wikipedia Agent | ✅ Complete | Summary fetching, error handling |
| Nominatim Agent | ✅ Complete | Geocoding and reverse geocoding |
| OpenMeteo Agent | ✅ Complete | Real-time weather data |
| Educational UI | ✅ Complete | 3-panel dashboard with reasoning display |
| Multi-Turn Conversations | ✅ Complete | Context preservation across queries |
PoC Success Metrics:
- ✅ All demo queries working (100% success rate)
- ✅ SPARQL validation operational (prevents injection)
- ✅ Thought visualization functional
- ✅ Multi-agent orchestration working
- Rate limiting with BullMQ
- DuckDuckGo web search agent
- Production frontend (SolidJS rewrite)
- Advanced error handling
- Performance metrics dashboard
- API documentation (OpenAPI/Swagger)
- Cloud deployment (Google Cloud Run)
- Authentication & user management
- Query caching & optimization
- Monitoring & observability (Prometheus/Grafana)
- Multi-language support
- Advanced SPARQL optimization
WikidAI is an educational project - contributions are welcome!
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes and test thoroughly
- Commit with clear messages:
git commit -m 'Add amazing feature' - Push to your fork:
git push origin feature/amazing-feature - Open a Pull Request
- Follow the existing TypeScript style (we use ESLint)
- Add tests for new agents or features
- Update documentation for significant changes
- Keep the educational focus - clarity over cleverness
- 🌍 New agents (e.g., DBpedia, Europeana, arXiv)
- 🎨 UI improvements (dark mode, mobile responsiveness)
- 📊 Better visualization of SPARQL queries
- 🧪 More comprehensive test coverage
- 📝 Documentation improvements or translations
- 🔧 Performance optimizations
- Gemini API Documentation
- Wikidata Query Service
- SPARQL Tutorial
- OpenStreetMap Nominatim
- Open-Meteo API
WikidAI was created by Giovanni Novelli Ph.D. for itWikiCon 2025 in Catania, Italy.
Special thanks to:
- The Wikimedia community for Wikidata and Wikipedia
- Google for the Gemini API
- OpenStreetMap contributors
- The open-source community
Author: Giovanni Novelli Ph.D.
- 🌐 Website: novelli.me
- 💼 GitHub: @gnovelli
- 📧 Email: giovanni@novelli.me
- 🔗 Project: novelli.me/wikidai
This project is licensed under the MIT License - see the LICENSE file for details.
Copyright © 2025 Giovanni Novelli Ph.D.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files, to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software.
- Issues: GitHub Issues
- Discussions: GitHub Discussions