indonesia-civic-stack: Instructions file for Codex

AGENTS.md — AI Agent Development Guide

This file helps AI coding agents (Claude Code, Codex, Cursor, etc.) work effectively in this repo.

Project Overview

indonesia-civic-stack is a Python SDK + MCP server + REST API that wraps 11 Indonesian government data portals into a unified interface. Every module returns CivicStackResponse.

Architecture

indonesia-civic-stack/
├── civic_stack/         # The installable package
│   ├── shared/          # Core shared code (DO NOT break these)
│   │   ├── schema.py    # CivicStackResponse — the universal envelope
│   │   ├── http.py      # civic_client(), fetch_with_retry(), proxy support
│   │   └── mcp.py       # CivicStackMCPBase — base class for MCP servers
│   ├── bpom/            # Example module (Food & Drug registry)
│   │   ├── scraper.py   # fetch() + search() — core logic
│   │   ├── normalizer.py # Raw HTML/JSON → structured dict
│   │   ├── router.py    # FastAPI routes
│   │   ├── server.py    # MCP server (FastMCP)
│   │   ├── app.py       # FastAPI app entry point
│   │   ├── Dockerfile
│   │   └── README.md
│   └── ... (one directory per government portal)
├── proxy/               # CF Worker proxy for geo-blocked portals
├── tests/               # VCR-based tests (no live portal calls in CI)
└── app.py               # Unified FastAPI app (all modules)

Key Patterns

Every module MUST follow this contract:

# civic_stack/<name>/scraper.py
async def fetch(query: str, *, proxy_url: str | None = None) -> CivicStackResponse:
    """Single-record lookup by ID."""

async def search(keyword: str, *, proxy_url: str | None = None) -> list[CivicStackResponse]:
    """Multi-result keyword search. Returns [] on not-found, never raises."""

HTTP client — always use civic_client():

from civic_stack.shared.http import civic_client, fetch_with_retry

async with civic_client(proxy_url=proxy_url) as client:
    response = await fetch_with_retry(client, "GET", url, rate_limiter=_limiter)