🗳️ IRIS Political Insight

🌐 Introduction

IRIS Political Insight is a platform for querying and analyzing Brazilian public electoral and parliamentary data. Built with InterSystems IRIS, Hybrid Search, and RAG (Retrieval-Augmented Generation), it integrates, structures, links, indexes, retrieves, and contextualizes official evidence from the Superior Electoral Court (TSE) and the Chamber of Deputies, with traceability back to the source.

Brazil is campaigning for the 2026 General Elections. What if exploring public electoral data were as simple as asking a question?

Portuguese version · Technical pipeline · Article in Portuguese

On October 4, 2026, 158,745,463 voters will be eligible to participate in Brazil’s General Elections, choosing representatives for six elective offices: President of the Republic, state governors, the Federal Senate, the Chamber of Deputies, state legislative assemblies, and, in the Federal District, the Legislative Chamber. A runoff election for president and governors will be held on October 25. Source: Superior Electoral Court (TSE).

Brazil publishes a significant amount of data on candidacies and parliamentary activity. The challenge is to transform distributed files, APIs, identifiers, and documents into information that people can actually explore.

Public data does not automatically mean accessible information. An investigation may require knowledge of government APIs, ZIP files, CSV files, PDFs, SQL, different identifiers for the same person, and multiple official systems. The goal is to reduce this barrier without replacing the original sources.

💡 The solution

The project brings together two complementary dimensions:

• the TSE provides the electoral context: candidacies, office, party, state, and government platforms when available;
• the Chamber of Deputies provides parliamentary context for candidacies that can be linked safely: history, external mandates, legislative proposals, authors, and topics.

A candidacy tells us who is running. Legislative data can add context about those who have already served as federal deputies. The link between the databases is deterministic and auditable, and parliamentary data is collected only when the link is classified as MATCHED.

On top of this foundation, the system combines structured filters, lexical search, and vector similarity; retrieves evidence; enriches each passage with data from its source entity; and asks the language model for a synthesis limited to the retrieved context.

🧭 Project principles

The system does not try to answer:

Who is the best candidate?

The goal is to answer exploratory questions using RAG:

“What do the available official sources say about this candidate and the topic being researched?”

“What is this candidate’s position on protecting children and adolescents online?”

“Does this candidate present proposals to combat violence in schools? What are they?”

“Which candidates have proposals related to reducing the 6x1 work schedule?”

“Which candidates present proposals for regulating social media and combating disinformation?”

“Which candidates have proposals related to the use of artificial intelligence in the public sector?”

These questions correspond to paths available in the implementation. The answer depends on the ingested scope and the available evidence.

The application does not:

• recommend how to vote;
• rank candidates;
• assign political scores;
• predict election results;
• automatically determine ideology;
• replace the reading of original sources.

The system provides information + context + evidence.

🏗️ Architecture

The implemented flow is collect → validate → link → persist → split → represent → retrieve → contextualize → explain.

                    Public sources
          TSE              Chamber
           │                  │
           └────────┬─────────┘
                    │
                Ingestion
                    │
                    ▼
           InterSystems IRIS
      ┌─────────────┼─────────────┐
      │             │             │
      ▼             ▼             ▼
  Candidate     Proposition   PoliticalChunk
  Relational     Relational      VECTOR
      │             │             │
      └─────────────┼─────────────┘
                    │
             Hybrid Search
           ┌────────┴────────┐
           │                 │
      Keyword Search    Vector Search
           │                 │
           └────────┬────────┘
                    │
                   RRF
                    │
                 Top K
                    │
                   LLM
                    │
                    ▼
             Answer + sources

There is no api container or Waitress. IRIS serves the Flask API; the second container contains only the Streamlit UI.

🧩 Implementations in the IRIS ecosystem

SQL handles what is deterministic, streams preserve documents, vectors approximate meanings, and the RAG context brings these representations together in the IRIS core.

🔎 RAG + Hybrid Search

Electoral data contains names, acronyms, parties, states, offices, numbers, and IDs that require exact matching. Human questions may also express the same concept using different words.

The LLM is not called when there is no valid evidence. The prompt requires neutral language, exclusive use of the [E1] and [E2] blocks, citations, and an explicit statement when context is insufficient. RAG does not eliminate hallucinations; it seeks to reduce them by conditioning generation on the retrieved material.

🏛️ Official sources

Each chunk retains its type, external ID, official URL, candidate, metadata, hash, and passage.

⚙️ Data pipeline

A single command processes TSE candidates, government platforms, Chamber matching and collection, and the RAG index. Downloads are validated, writes are idempotent, chunks use 700 tokens with an overlap of 100, and text-embedding-3-small produces 1,536 dimensions.

See PIPELINE.pt.md for contracts, matching, transactions, pagination, hashes, failures, chunking, and retrieval. The README does not duplicate that documentation.

🧪 Reproducible demonstration

After ingestion, open http://localhost:8501, select a candidate — or “All candidates” — and ask a question. The interface displays the answer and sources.

Test the flow through the API without selecting an ID manually:

$candidates = Invoke-RestMethod http://localhost:52773/api/candidates
$candidate = $candidates.items | Select-Object -First 1
$body = @{ question = "Which topics appear most frequently in this candidate's legislative proposals?"; candidateId = [int]$candidate.id } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri http://localhost:52773/api/ask -ContentType "application/json" -Body $body

question
  → deterministic planning
  → structured query or Hybrid Search
  → chunk + structured source data
  → context [E1]...[En]
  → LLM
  → answer + sources[] with official URL

The repository does not contain screenshots, so no prefabricated answer is presented as an actual result. Outputs vary according to scope, collection, and official data.

🚀 Running the project

📋 Requirements

• Docker with Compose v2;
• access to intersystems/iris-community:latest-cd;
• an OpenAI key for embeddings, vector search, and /ask;
• available ports 1972, 52773, and 8501;
• Python 3.12 only for local development and testing.

1. 📥 Clone

This checkout does not have an origin configured; use the HTTPS URL displayed on the published page:

$repositoryUrl = Read-Host "Repository HTTPS URL"
git clone $repositoryUrl
Set-Location tse-iris-rag

2. 🔧 Configure

Copy-Item .env.example .env
notepad .env

On Linux/macOS, use cp .env.example .env. Fill in at least:

LLM_API_KEY=your-openai-key

The example uses the 2026 election, the state of SP, and the offices in INGEST_OFFICES. Reduce the number of states, offices, and Chamber limits if you want a smaller load.

3. 🏗️ Build and initialization

docker compose up --build -d
docker compose ps

Wait for iris to become healthy and for ui to be running.

4. ❤️ Health checks

Invoke-RestMethod http://localhost:52773/api/health
Invoke-WebRequest -UseBasicParsing http://localhost:8501/_stcore/health

Expected results: {“status”:“ok”} and ok.

5. 📦 Ingestion

docker compose exec iris irispython -m app.ingestion.pipeline

The command queries public services and generates embeddings; duration and volume vary. To rebuild only the already persisted chunks and embeddings:

docker compose exec -T iris irispython -m app.ingestion.chunk_index

6. ✅ Validation and access

Invoke-RestMethod http://localhost:52773/api/candidates

• interface: http://localhost:8501
• API: http://localhost:52773/api

7. 🧪 Local tests

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements-dev.txt
pytest -m unit
ruff check app tests wsgi_app.py
mypy app wsgi_app.py

Integration and smoke tests require IRIS/Docker to be running and the RUN_IRIS_TESTS=1 and RUN_SMOKE_TESTS=1 variables, respectively.

🛠️ Essential troubleshooting

docker compose down preserves the volume. docker compose down -v deletes the IRIS data.

📁 Structure

app/
├── api/          # Flask and HTTP contracts
├── config/       # validated configuration
├── database/     # SQL, DB-API, Object API, and transactions
├── embeddings/   # embeddings
├── ingestion/    # TSE, Chamber, matching, and chunking
├── rag/          # context, prompt, and generation
├── repositories/ # IRIS persistence
├── retrieval/    # structured, lexical, vector, and RRF
└── ui/           # Streamlit
iris/             # eight ObjectScript classes
tests/            # unit, integration, and smoke tests
docs/             # specifications, decisions, and audits

📚 Documentation

• Technical pipeline
• Specification
• Implementation plan
• TSE + Chamber + IRIS ingestion
• IRIS classes and mapping
• WSGI migration
• Technical article

🏆 InterSystems Contest 2026

The project competes in the RAG category of the InterSystems PT 2026 Contest.

The development method using OpenAI Codex, specification prompts, human review, and actual corrections is described in ARTICLE.pt.md.

⚖️ License and responsibility

Code released under the MIT License.

Independent project, with no affiliation with the TSE, the Chamber, candidacies, or political parties. It organizes public information and does not replace official sources or the voter’s judgment.

👤 Author

• LinkedIn
• InterSystems Developer Community
• InterSystems Open Exchange