Ò Capistaine

Making local democracy accessible through AI — because understanding your town council shouldn't require a law degree.

"This year, I will finally understand my local elections and get involved as a citizen." — Our 2026 resolution

🎬 Demo

Watch the 3-minute demo →

Overview

Ò Capistaine is an AI-powered civic transparency platform that crawls, processes, and makes accessible 6 years of municipal documents (arrêtés, délibérations, commission reports) for Audierne, France. It serves as a training ground for civic AI agents that help citizens engage with local democracy.

Key Features:

• 🤖 Forseti 461 Agent: Charter validation, category classification, wording correction
• 🔒 PII Anonymization: Regex for transcripts (Speaker_1, Speaker_2...), LLM for general docs
• 🔄 Provider Failover: Multi-LLM support (OpenAI, Gemini, Claude, Mistral, Ollama) with automatic failover
• ✨ Contribution Wizard: 5-step guided workflow for citizen contributions
• 🔍 Document Intelligence: 4,000+ municipal documents indexed (Firecrawl + OCR)
• 📊 LLM Observability: Full tracing via Opik with cost tracking and scheduled evaluation
• 🔗 Multi-channel Integration: Facebook, email, chatbot via Vaettir N8N workflows
• 🌐 Bilingual Interface: French/English with real-time switching

The platform supports audierne2026.fr, a real participatory democracy initiative.

For Judges & Evaluators

New to OCapistaine? Start here:

Resource	Description
Getting Started	Overview of the platform and quick start
Judge Trial Guide	Step-by-step guide to test Forseti validation

Quick Test:

1. Open the Streamlit app
2. Select OpenAI provider in sidebar
3. Go to Batch Validation → Single Contribution Test
4. Click Random to load a real contribution (with English translation)
5. Click Generate Variations to create test cases
6. Validate each to see Forseti in action

Tech Stack

Component	Technology	Purpose
Data Validation	Pydantic	Schema validation for documents and API models
Web Scraping	Firecrawl	Municipal document acquisition with OCR
Scheduling	APScheduler	Periodic crawl jobs and data refresh
LLM Observability	Opik (cloud)	Tracing, evaluation, and LLM-as-judge
API	FastAPI	REST endpoints for N8N integration
Orchestration	N8N (Vaettir)	Multi-channel workflows (FB, email, chatbot)

Quick Start

# Clone with submodules
git clone --recurse-submodules https://github.com/locki-io/ocapistaine.git
cd ocapistaine

# Install dependencies
poetry install

# Configure environment
cp .env.example .env
# Edit .env with your API keys

# Run crawler
python src/crawl_municipal_docs.py --source all --mode scrape

Running the Application

1. Start the Streamlit UI

The primary way to start the OCapistaine interface is via the unified startup script. It handles environment configuration, port management, and optional public access.

# Start the interactive UI
./scripts/run_streamlit.sh

Access Point:

• Local: http://localhost:8502

2. Start the API Backend (Optional)

If you need the REST API or N8N/Vaettir webhook integrations, start the FastAPI server in a separate terminal:

# Start FastAPI backend
poetry run uvicorn app.main:app --host 0.0.0.0 --port 8050 --reload

Access API documentation at http://localhost:8050/docs.

VS Code Integration

Tasks (Cmd+Shift+P → "Tasks: Run Task"):

Task	Description
🚀 Start OCapistaine (Local)	One-click local startup
🛑 Stop OCapistaine	Stop the Streamlit process
📊 Check Status	View running services status
🔗 Open in Browser	Open http://localhost:8502

Debug Configurations (F5 or Run & Debug panel):

Configuration	Description
Run Uvicorn (Poetry)	Start FastAPI server on port 8050 with debugger
Run Streamlit (Debug)	Start Streamlit UI on port 8502 with debugger
Full Stack (Uvicorn + Streamlit)	Both services with debugging

Quick Start:

• Press Cmd+Shift+B to run the default build task (starts everything)
• Or use the Run & Debug panel to select a configuration

version control on main, dev and feature branch

main requires approval
dev no approval but linear history

To keep our history clean (no noisy merge commits on feature branches):

1. Run once:
   git config --local pull.rebase true
   # (or git config --local pull.rebase merges)

   Optional safety layer:
   git config --local pull.ff only

   → git pull will now rebase by default (clean linear history)
   → if it can't fast-forward, it fails instead of auto-merging

This way:
- Your local git pull stays clean
- Main/dev stays perfectly linear
- No more "Merge branch 'feature/ocr-…' into dev" spam

Project Structure

ocapistaine/
├── app/                       # Streamlit UI + Forseti agent + services
├── src/                       # Document crawlers (Firecrawl, OCR)
├── docs/                      # Git submodule → docs.locki.io
└── ext_data/                  # 4,000+ scraped municipal documents

For detailed architecture, see docs.locki.io:

• Application — Streamlit UI, Forseti agent, scheduler
• Architecture — System design and data flow
• Orchestration — Docker, N8N, observability

Working with Submodules

The docs/ directory is a git submodule pointing to locki-io/docs.locki.io.

Clone with submodules

git clone --recurse-submodules https://github.com/locki-io/ocapistaine.git

If already cloned without submodules

git submodule update --init --recursive

Update docs to latest

git submodule update --remote docs
git add docs
git commit -m "Update docs submodule"

Work on documentation

cd docs
npm install
npm start    # Dev server at localhost:3000
npm run build

Commit changes to docs

# Inside docs/
git add .
git commit -m "Your changes"
git push

# Back in parent repo
cd ..
git add docs
git commit -m "Update docs submodule"
git push

Related Repositories

Repository	Status	Description
Vaettir	✅ Operational	N8N workflows connecting OCapistaine to audierne2026, Facebook, email
docs.locki.io	✅ Live	Technical documentation + hackathon journey blog
audierne2026/participons	✅ Live	Public participation platform (Jekyll)

Authentication

The public instance is password-protected. Configure in .streamlit/secrets.toml:

[auth]
password = "your-secret-password"

Setup:

# Copy template
cp .streamlit/secrets.toml.example .streamlit/secrets.toml

# Edit with your password
nano .streamlit/secrets.toml

For hashed passwords (more secure):

poetry run python -c "from app.auth import hash_password; print(hash_password('your-password'))"
# Then use: password = "sha256:..."

Disable authentication (local development): Remove or leave empty the password field.

Environment Variables

Variable	Description	Example
FIRECRAWL_API_KEY	Firecrawl API key for web scraping
OPIK_API_KEY	Opik API key for LLM observability
OPIK_WORKSPACE	Opik workspace name
STREAMLIT_PORT	Local Streamlit port	8502
DISCORD_INVITE_URL	Discord invite link for auth page	https://discord.gg/yourserver

See .env.example for a complete template.

Project Board

Track progress: github.com/orgs/locki-io/projects/2

Contributing

Important for Hackathon Participants: Please read CONTRIBUTING.md before submitting code.

This project uses a dual-license structure. By contributing, you agree to the license terms for the component you're working on. See CONTRIBUTING.md for details.

License

This project uses a dual-license structure:

Component	License	Files
Core infrastructure	Apache 2.0	src/, docs/, utilities
Agent workflows & prompts	Elastic License 2.0	agents/, workflows/

Summary

• Open source components: Crawlers, utilities, documentation - free to use, modify, distribute
• Source-available components: Agent orchestration, prompts, N8N workflows - visible but commercial use requires license from locki.io

See LICENSE and LICENSE-ELv2 for full terms.

Hackathon Note

This structure complies with hackathon open-source requirements while protecting locki.io engineering IP for future commercialization.

---

Roadmap

Current Status

Feature	Status	Notes
Document Crawling	✅ Operational	4,000+ docs indexed
Forseti 461 Agent	✅ Operational	Charter validation, classification
PII Anonymization	✅ Operational	Transcript + LLM modes
Contribution Wizard	✅ Operational	5-step workflow
Provider Failover	✅ Operational	Multi-LLM support
RAG (Retrieval)	🚧 In Development	Document search pending

Upcoming

March 2026 - Audierne Elections Sprint

The municipal elections in Audierne start March 18th, 2026. During this period, the dev branch will be pushed to its maximum capacity to support real citizen engagement.

• Firecrawl Integration: Move document crawling into the processors workflow for scheduled updates
• RAG Pipeline: Full retrieval-augmented generation for document Q&A
• Real-time Contribution Tracking: Live dashboard for election period

Deployment Strategy

Branch	Environment	Purpose
main	Render (cloud)	Stable demo for hackathon judges
dev	Local + ngrok	Active development, election support

This ensures judges always have access to a stable, running application while development continues at full speed for the elections.

---

🏆 Encode Hackathon 2026

Ò Capistaine was built for the Encode AI Hackathon 2026.

Resource	Link
🎬 Demo Video	youtu.be/EAZiVUMtfp8
📚 Documentation	docs.locki.io
📝 Hackathon Journey	Blog posts
📊 Project Board	GitHub Project

Built with ❤️ for local democracy in Audierne, Brittany, France.