sicop_mcp

Сервер данных SICOP (государственные закупки Коста-Рики, открытые данные 2020–2026) предоставляется как REST API и как MCP-сервер для ИИ-ассистентов.

• Данные: Salidas/ из пакета SICOP (~4,3 млн строк загружено в Postgres в 31 таблицу: 13 наборов по годам 2020–2026 + 18 производных таблиц gold).

• Стек: Django 6 + DRF + Celery + Postgres + Redis. Тот же паттерн, что и mwt/consola-mwt-one.

• Правило домена: каждая бизнес-цифра поставщика объявляет свой уровень измерения (captacion = присуждение · ejecucion = заказы · entrega = приёмки).

Локальный запуск

Требуется: Python 3.12+ (проверено на 3.14), локальный PostgreSQL 16/18, Redis (или используемый брокер).

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

# crear DB (una vez):
#   createuser -U postgres sicop -P
#   createdb -U postgres -O sicop sicop

python manage.py migrate
python manage.py load_sicop --sync     # carga los CSV de Salidas/ (SICOP_DATA_DIR en .env)
python manage.py runserver 127.0.0.1:8000

Загрузка данных через Celery (паттерн стека)

celery -A config worker -l info        # worker
python manage.py load_sicop            # encola una tarea por archivo
python manage.py load_sicop --only contratos --force

MCP-сервер

python -m sicop.mcp_server                            # stdio (para clientes MCP)
python -m sicop.mcp_server streamable-http --port 9010  # HTTP

MCP-инструменты (18): sicop_ficha_proveedor (ejecucion против captacion), sicop_mercado_familia, sicop_competencia_procedimiento, sicop_producto, sicop_producto_historia (ряд цен по годам), sicop_cara_a_cara (два поставщика), sicop_expediente, sicop_adjudicaciones, sicop_carteles_objetados, sicop_representantes, sicop_representante_competencia, sicop_excepciones, sicop_sanciones, sicop_precios_institucion, sicop_perdidas_baratas (предложил дешевле и проиграл), sicop_campo_buscar, sicop_regimen_evaluacion, sicop_resumen.

Каждый бизнес-ответ несёт конверт (envelope из плана §5.4): nivel_medicion, cobertura_cruce (0.626), moneda и caveats.

REST API

Фильтры по равенству с точным именем столбца (CEDULA_PROVEEDOR, NRO_SICOP, ANO, ...) и ?search= в ресурсах с текстом.

Related MCP server: chile-procurement

ФАЗА 2 — ежедневный цикл (cron 06:00)

python manage.py ciclo_diario               # corrida manual del ciclo
celery -A config worker -l info             # worker (ya en tu stack)
celery -A config beat -l info               # cron: ciclo-diario 06:00 · vigilancia 06:05 · consolidar 06:15

• Ежедневный цикл: наблюдение за перезаписью (текущий месяц + 3 закрытых + 2 ротационных) → консолидация PENDIENTES результата → сигналы watchlist → приоритетная очередь → gold + tests-gate.

• resultado_decision (SCH_RESULTADO v1, /api/v1/resultados/, POST /api/v1/resultado-registrar/): зерно (nro_sicop, nro_linea, decision_id), append-only, обязательный замороженный контекст (build_id/snapshot_ts/modelo_version/features_hash), override как ключевое поле.

• Сигналы (/api/v1/senales/): cliente_participa/adjudicado/perdio, cartel_objetado, sancion_nueva, institucion_vigilada, perdio_por_poco (watchlist.json).

• Наблюдение (/api/v1/vigilancia/): ETag/Content-Length целевых месяцев против ctl_mes_fuente.

MCP-инструменты: sicop_registrar_resultado, sicop_resultado, sicop_senales, sicop_vigilancia, sicop_ciclo_diario, sicop_consolidar_resultados.

ФАЗА 3 — физическое принуждение + два трека + журнал

• Принуждение (/api/v1/politica/): middleware, который блокирует с 403 любой запрос с сырыми путями (/salidas/, .csv, .zip, file://, ..\) или секретами; тесты политики (никакого свободного SQL, никакого смешения валют, никаких сырых путей) → 5/5 PASS.

• Два трека: SICOP_CARRIL=operacion (канонический) или SICOP_CARRIL=laboratorio (каждый ответ помечен NO_APTO_PARA_DECISION, decision_eligible:false). Трек лаборатории добавляет инструмент sicop_lab_sql (SQL только для чтения, только SELECT/WITH, максимум 200 строк, отклоняет DELETE).

• Журнал ответов (/api/v1/registro/, инструмент sicop_registro): каждый вызов MCP и запрос API попадает в registro_respuesta (агент, инструмент, params, build_id, счёт, трек, длительность, статус).

ФАЗА 4 — тест (карточка ESOSA, backtest, holdout) + незакрытые P1–P11

python manage.py fase4 --json        # ficha ESOSA desde gold + backtest + holdout (gate de muerte)
python manage.py pendientes --json   # P1-P7

• Карточка ESOSA (/api/v1/prueba-fase4/?solo=ficha, инструмент sicop_ficha_esosa): воспроизведена из канонического слоя — ТОЧНОЕ desempeno (98,6% / 577 строк), captacion воспроизводит паттерн (пик 2022, коллапс 2023), competencia/cara-a-cara ограничены покрытием кросса (62,6%) до загрузки восстановленного.

• Backtest (инструмент sicop_backtest_invitaciones): повтор прошлых приглашений (необходимая скидка для победы).

• Holdout + gate смерти (инструмент sicop_holdout): обучение <=2024, тест 2025–26; если модель не превосходит якорь из тендера, она отбрасывается (остаётся память + наблюдение).

• Незакрытые: p1_conversion_cartera (неявный курс 460–690 CRC/USD, официальный BCCR gate ожидается) · p3_catalogo_familias (9 295 производных семейств) · p5_recurrente_vs_recurrido · p6_sanciones_vigencia (1 санкционированный, выигрывающий действующий) · p7_tamano_historico (изменение 1,04% → не SCD2) · p10_bronze_zip_miembro (bronze из zip, буквальная сырая строка). P11 resultado_decision закрыт в ФАЗЕ 2.

Дополнения плана — Atlas, CGR, BCCR

• Atlas (/atlas/): приложение для навигации по корпусу. Решения плана соблюдены: ни одна цифра не путешествует одна (каждый экран показывает свой конверт), качество входит первым (/atlas/calidad/: производные по годам, tests-gate, прогоны, наблюдение, ловушки), заблокированные ловушки не документируются (UI предупреждает о сравнении валют и цен cross-год без CL), и приложение придаёт лицу harness (сигналы дня видны). Экраны: дашборд, поиск, поставщики, карточка поставщика, продукт (история), процедура (expediente+competencia+régimen+invitados+recursos), рынок по семейству.

• Поиск CGR (/api/v1/cgr/?termino=, инструмент sicop_cgr_buscar): PDF-файлы резолюций с нативным текстом. ЦЕЛЕВОЕ ИСПОЛЬЗОВАНИЕ, не сплошное сканирование; юридический gate ожидается (термины CGR не прочитаны).

• Курс BCCR (/api/v1/bccr-tc/?fecha=, инструмент sicop_bccr_tc): официальный BCCR (серии 317/318) если BCCR_TOKEN/BCCR_EMAIL в .env; без токена возвращается неявный курс источника (медианный годовой CRC/USD) с пометкой.

• Приглашения: загружено 42,2 млн строк + invitados_vs_ofertantes.

Docker (VPS)

docker compose up -d --build
# expone 8400 -> django (puerto libre, no choca con 8100 de consola-mwt-one), con Salidas montado en /data/salidas

ФАЗА 1 — канонический слой (bronze + silver + control)

python manage.py fase1                # bronze -> silver (6 hechos) -> tests-gate -> gold atomico
python manage.py fase1 --solo-tests   # solo correr los tests como gate
python manage.py recalcular_derivadas # producto_firma, recursos_desenlace, tiempos_por_etapa, precios_identicos, invitados_vs_ofertantes, regimen_evaluacion, ctl_deriva, catalogo_campo

• Bronze (/api/v1/bronze/): неизменяемая сырая строка + HASH_FILA + CORRIDA_ID + месяц.

• Silver — 6 фактов (правильное зерно, DECIMAL(18,4), тройка валют, битемпоральность OBSERVADO_DESDE/HASTA/ES_VIGENTE): /fact-requerimiento (тендер, proc x строка x статья) · /fact-oferta (proc x оферта x строка) · /fact-adjudicacion (акт x proc x строка x поставщик) · /fact-contrato-linea · /fact-orden (одна строка на NRO_ORDEN, TOTAL_ORDEN один раз, только CRC суммируется) · /fact-recepcion.

• Control (/api/v1/ctl-*): прогон, исходный месяц (хэш zip), схема, карантин, тесты как gate.

• catalogo_campo (/api/v1/catalogo-campo/): навигационный словарь данных (тип, заполненность, ключ, ловушка, единица, правило join).

• Атомарная публикация: gold не публикуется, если тест gate падает (остаётся предыдущая версия).

MCP-инструменты: sicop_fact_requerimiento/oferta/adjudicacion/contrato/orden/recepcion, sicop_catalogo_campo, sicop_ctl_deriva, sicop_regimen, sicop_competencia_por_regimen, sicop_gold_status.

Данные

• УРОВЕНЬ ИЗМЕРЕНИЯ: cartera сравнивает MONTO_EJECUTADO_CRC (только колоны, дедупликация по NRO_ORDEN) с MONTO_ADJUDICADO_CRC. Измерение по присуждениям занижает до 59 раз (случай SONDEL 2026: 64 раза).

• Валюты: заказы содержат 5 валют (CRC/USD/EUR/JPY/GBP); суммируются только колоны.

• Покрытие: competencia_por_linea покрывает 62,6% кросса оферта x оферент (задокументировано в пакете).

• Конфиденциальность: inhibiciones содержит должностных лиц; не публиковать консолидации без явного решения (Закон 8968).

• Очистка: недопустимые ячейки сумм/дат загружаются как NULL (учитываются в estado-carga).