A domain-specific AI agent for satellite frequency coordination and spectrum management, grounded in the ITU Radio Regulations and ITU-R Recommendations.
An AI agent that reads the ITU Radio Regulations (Articles, Appendices, Resolutions, and Recommendations), runs propagation and link budget calculations, and answers satellite frequency coordination questions with cited, verifiable references to specific RR provisions.
Satellite frequency coordination is governed by a four-volume legal instrument with thousands of cross-referenced provisions. Existing tools are decades old, generic LLMs hallucinate provision numbers, and consulting firms charge enterprise rates. This project bridges the gap with grounded retrieval, deterministic engineering tools, and explicit citation verification.
┌─────────────────────────────────────────────────────────────────┐
│ Flutter Desktop App │
│ Chat · Tool Catalog · Provision Browser · Ingestion · Settings │
└─────────────────────────┬───────────────────────────────────────┘
│ HTTP + SSE
┌─────────────────────────▼───────────────────────────────────────┐
│ FastAPI │
│ /chat /search /tools /chunks /ingest /health │
└─────────────────────────┬───────────────────────────────────────┘
│
┌─────────────────────────▼───────────────────────────────────────┐
│ LangGraph Agent Pipeline │
│ │
│ START → router → [calculation?] │
│ yes → collect_inputs → [complete?] │
│ yes → execute_tools │
│ no → responder (ask user) │
│ no → researcher → cross_reference ↻ │
│ └──────→ responder │
└───────┬────────────────────────┬────────────────────────────────┘
│ │
┌───────▼────────┐ ┌───────────▼──────────────────┐
│ Hybrid │ │ Tool Registry │
│ Retriever │ │ (7 deterministic tools) │
│ ChromaDB + │ │ ΔT/T · Link Budget │
│ NetworkX │ │ Rain · Gaseous · PFD │
│ graph store │ │ Coordination · Allocation │
└────────────────┘ └──────────────────────────────┘
| Node | Role |
|---|---|
router |
Three-stage intent detection (anchor map → regex → LLM); maps user queries to tools or retrieval |
researcher |
Exact-match JSONL lookup + ChromaDB semantic search; feeds retrieved provisions downstream |
cross_reference |
Extracts intra-document citations and queues bounded re-fetch loops |
collect_inputs |
Parses tool arguments from user text and uploaded .txt files; identifies missing required fields |
execute_tools |
Invokes registered tools with validated inputs; wraps results with ITU citations |
responder |
Final answer generation — formats retrieved provisions with citations or presents tool results verbatim |
All tools subclass BaseTool, expose a Pydantic input_schema, and return results with verbatim ITU-R citations.
| Tool | Standard | Description |
|---|---|---|
delta_t_over_t |
RR Appendix 8 | Interference-to-noise ratio (ΔT/T) for uplink and downlink contributions |
link_budget |
Friis / RR Art. 22 | End-to-end link power balance (EIRP, path loss, G/T, Eb/N₀, margin) |
rain_attenuation |
ITU-R P.618 | Rain fade prediction for microwave/mm-wave satellite links |
gaseous_absorption |
ITU-R P.676 | Atmospheric absorption by O₂ and H₂O along a slant path |
pfd_check |
RR Table 21-4 | Power flux density limit validation at the Earth's surface |
coordination_trigger |
RR Art. 9.7/9.11A/9.12 | Determines whether coordination is required between satellite networks |
frequency_allocation |
RR Article 5 | Band lookup and coordination trigger thresholds for satellite services |
Supporting utilities: link_geometry (slant range, elevation, FSPL) and unit_converter (frequency, power, gain conversions).
- ChromaDB vector store — multi-collection indexing of Articles, Appendices, Recommendations, and Resolutions at provision-level granularity
- NetworkX graph store — intra-document cross-reference graph extracted from ITU PDF typography; enables graph-expansion of search results
- HybridRetriever — keyword pre-fetch, vector search, graph expansion, and cross-encoder reranking in a single pipeline
- Provision JSONL store — exact-match lookup by document type and provision number
| Component | Role |
|---|---|
pipeline.py |
Orchestrator; discovers PDFs, dispatches to parsers, runs cross-reference resolution, writes JSONL outputs |
article_parser |
RR Articles (1, 5, 9, 11, 21, 22, …) |
appendix_parser |
RR Appendices (4, 5, 7, 30, 30A, 30B, …) |
recommendation_parser |
ITU-R Recommendations (P-series, S-series, …) |
resolution_parser |
WRC Resolutions |
pdf_extractor |
Low-level text, table, and font extraction via PyMuPDF |
table_extractor |
Frequency allocation table extraction |
footnote_extractor |
Footnote extraction and linking |
cross_ref_resolver |
Cross-reference graph construction |
| Endpoint | Method | Description |
|---|---|---|
/chat |
POST | SSE stream: session_start, agent_step, retrieval, semantic, tool_result, needs_input, final, error |
/search/{query} |
GET | Hybrid search across all provisions |
/tools |
GET | Tool specs (for LLM function calling) |
/tools/{tool_name} |
POST | Direct tool invocation |
/chunks |
GET | Paginated provision list |
/chunks/{id} |
GET | Provision detail |
/ingest |
POST | File upload for batch ingestion |
/health |
GET | Service status and version |
ChatRequest accepts an optional data_file_text: str field for inline .txt file uploads (satellite network data).
Configurable via .env. Supported providers:
- Ollama (default) — local inference; tested with
qwen2.5:14b-instruct-q4_K_M - OpenAI-compatible — works with OpenAI, DeepSeek, Together, or any vLLM endpoint
Unit tests (12 files): article parser, cross-reference resolver, ΔT/T tool, frequency allocation, gaseous absorption, input collection, link budget, path loss/geometry, PDF extractor, rain attenuation, coordination trigger, execute-tools node.
Integration tests (3 files): full agent graph flow, chat API with SSE streaming, ingestion pipeline.
# Run all tests
pytest backend/tests/
# Run with coverage
pytest --cov=itu_assistant backend/tests/Flutter desktop application (Windows primary). Built with Riverpod for state management, Freezed for immutable models, and Hive for local persistence.
- Auto-scrolling conversation view with Markdown rendering
- Clickable citation chips that navigate to the full provision text
- Expandable agent trace panel showing each graph node, duration, and sub-events
- Real-time SSE streaming — token-level updates as the agent runs
- Tool call cards showing pending invocations with their inputs
- Tool result cards showing formatted calculation outputs (ΔT/T, link budget, etc.)
- Missing input form — dynamically generated from the tool's Pydantic schema; collects missing arguments without leaving the chat
- Browse all 7 registered tools with descriptions and ITU references
- Filter by tool name or standard
- Dynamic tool form — generated from each tool's JSON schema; submit directly without going through the agent
- Result view with citations and engineering notes
- Searchable, filterable list of all ingested provisions
- Filter by document type (Article / Appendix / Recommendation / Resolution) and identifier number
- Frequency search dialog — filter by frequency band or allocation service
- Full provision detail view with formatted text and cross-reference links that navigate to related provisions
- Stats screen — document counts, indexing date, ChromaDB collection sizes
- File picker for uploading ITU PDFs (
.pdf) or data files (.txt) - Document type selector before upload
- Real-time ingestion status and progress
- Preview of parsed provisions before committing to the store
- Configure backend API base URL
- One-click connection test against
/health - App version and backend version display
- Settings persisted locally via Hive
- Command palette (Ctrl+K) — keyboard-driven search across provisions and tools
- SSE client for streaming chat events
- Configurable HTTP client with error handling and retry
- Sealed
Failuretypes for consistent error propagation - Freezed models with JSON serialization for all API contracts
- Python 3.11+
- Flutter SDK (stable channel) — for the desktop UI
- Ollama running locally with
qwen2.5:14b-instruct-q4_K_M
(or configure an OpenAI-compatible endpoint in.env) - ITU PDFs placed under
data/raw/— seedata/raw/MANIFEST.md
# Clone
git clone https://github.com/<your-username>/itu-rr-assistant.git
cd itu-rr-assistant
# Create venv and install (Windows PowerShell)
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt -r requirements-dev.txt
pip install -e ./backend
# Copy env template
copy .env.example .env
# Edit .env: set LLM_PROVIDER, model names, paths as needed# 1. Ingest the ITU corpus (one-time; rebuilds ChromaDB and JSONL stores)
python backend/scripts/ingest_all.py
# 2. Start the API server
uvicorn itu_assistant.api.main:app --reload --port 8000
# 3. (Optional) Run a query without the UI
python backend/scripts/run_query.py "What is the coordination procedure under Article 9.7?"
# 4. Run the Flutter desktop UI (separate terminal)
cd frontend
flutter run -d windowsThe eval suite runs E2E scenarios against real ITU-RR questions and scores answers on two metrics: citation-match recall (does the answer cite the right provisions?) and keyword overlap (does the answer contain the expected domain terms?). Pass threshold is a composite score ≥ 0.6.
| Backend | Scenarios | Pass Rate | Avg Composite | Avg Citation | Avg Keyword |
|---|---|---|---|---|---|
| Original (reference) | 17 | 94.1% (16/17) | 0.921 | 0.943 | 0.899 |
| Claude | 20 | 85.0% (17/20) | 0.779 | 0.772 | 0.786 |
| Category | Count | Pass Rate | Avg Composite |
|---|---|---|---|
| appendix | 2 | 100% | 0.881 |
| article1 | 2 | 100% | 1.0 |
| article11 | 2 | 100% | 0.834 |
| article5 | 3 | 100% | 0.755 |
| article9 | 3 | 67% | 0.766 |
| crossref | 3 | 33% | 0.625 |
| integrity | 2 | 100% | 0.750 |
| interference | 3 | 100% | 0.739 |
| Difficulty | Count | Pass Rate | Avg Composite |
|---|---|---|---|
| easy | 3 | 100% | 0.894 |
| medium | 6 | 100% | 0.813 |
| hard | 11 | 73% | 0.729 |
| Tool | Result | Notes |
|---|---|---|
| Link Budget | 5/5 ✅ | |
| Rain Attenuation | 5/5 ✅ | |
| Gaseous Absorption | 4/4 ✅ | |
| PFD Check | 5/5 ✅ | |
| Coordination Trigger | 5/5 ✅ | |
| Frequency Allocation | 0/2 ❌ | Needs Article 5 table ingestion |
# Run full eval suite
.\make.ps1 eval
# Run with category/difficulty filters
python evaluate.py --categories article9 appendix --difficulties hard
# Toggle individual metrics
python evaluate.py --citation --no-keyword --judgeSee docs/EVALUATION.md for full methodology and evals/results/ for per-scenario reports.
| Phase | Status |
|---|---|
| Week 1 — Ingestion foundation | ✅ Complete |
| Week 2 — Full corpus + vector store | ✅ Complete |
| Week 3 — Engineering tools | ✅ Complete |
| Week 4 — Agent orchestration | ✅ Complete |
| Week 5 — API + frontend | ✅ Complete |
| Week 6 — Polish + eval suite | 🟡 In progress |
MIT — see LICENSE.
The ITU PDFs themselves are not redistributed in this repository. Users must obtain them
directly from the ITU. See data/raw/MANIFEST.md for the exact
editions and sources.