insseption

JSON API + Python client for INSSE TEMPO-Online (Romania’s National Institute of Statistics).

• HTTP JSON API — open /api/v1/... in a browser; responses are indented application/json
• Python package — from insseption import Client
• UI — chat-first front page at / (Ask TEMPO agent); JSON discovery at /api

Production: https://insse.csaladen.es

INSSE reuse terms

Python client

Published on PyPI:

pip install insseption

From source / GitHub (optional):

pip install "git+https://github.com/csaladenes/insseption.git"

from insseption import Client

with Client() as c:                       # https://insse.csaladen.es/api/v1
    print(c.health())
    print(c.context(lang="en")["nodes"][:3])
    meta = c.matrix("POP105A", lang="en")
    data = c.query("POP105A", lang="en")  # default totals / latest year
    print(data["columns"], data["row_count"])

Point at a local server:

Client("http://127.0.0.1:8787/api/v1")

CLI:

insseption --base-url http://127.0.0.1:8787/api/v1 health
insseption --base-url http://127.0.0.1:8787/api/v1 query POP105A

JSON API (/api/v1)

Interactive docs: /docs · OpenAPI: /openapi.json

Example in browser:

https://insse.csaladen.es/api/v1/matrices/POP105A/query?lang=en

POST body:

{
  "lang": "en",
  "selections": { "5": [4931], "1": [1] }
}

Run the API locally

python3.11 -m venv .venv && source .venv/bin/activate
pip install -e ".[server]"
uvicorn insseption.main:app --host 127.0.0.1 --port 8787

Deploy (Docker / Traefik)

Example host layout (adjust to your stack):

• App path: ./insseption/ next to your compose file
• Service: insseption (+ optional insseption-agent)
• Traefik host rule: insse.csaladen.es → :8787
• Networks: public edge + internal

# on the host
# sync ./insseption (rsync --exclude .env) and ensure ./insseption/.env (OPENROUTER_API_KEY)
docker-compose up -d --build --no-deps insseption
curl -sS https://insse.csaladen.es/api/v1/health

Guide: https://insse.csaladen.es/docs

Chat agent (separate container)

NL agent in ./agent (OpenRouter → TEMPO via the JSON API). The agent container stays on the internal Docker network; the API reverse-proxies /agent/*. The chat UI is the site front page at /.

docker-compose up -d --build --no-deps insseption insseption-agent
curl -sS https://insse.csaladen.es/agent/health

Host smoke harness

# API + docs + chat home + agent against production (or set INSSEPTION_HOST)
python3 scripts/harness.py
# lighter API-only check:
INSSEPTION_BASE=https://insse.csaladen.es/api/v1 python3 scripts/smoke.py

License

MIT — © Dénes Csala (GitHub). Data remains subject to INSSE reuse terms.