nport

Нормализованный граф позиций фондов и поставщиков услуг, построенный на основе форм SEC N-PORT и N-CEN, объединённый с реестром LEI от GLEIF и предоставляемый агентам через MCP.

Дизайн: docs/design.md. Эмпирические заметки об исходных данных: docs/data-notes.md.

Статус: только слой приёма данных. Слои Raw и Parquet полностью загружаются; dbt-трансформация, MCP-сервер и Terraform ещё не построены.

Быстрый старт

uv sync
export SEC_USER_AGENT="Your Name your@email.com"   # the SEC throttles anonymous traffic

uv run nport-ingest periods nport    # what quarters are published upstream
uv run nport-ingest all              # N-PORT + N-CEN + GLEIF, latest available
uv run nport-ingest status           # what is landed, from the manifests

Загрузка всех трёх источников занимает несколько минут и записывает ~1 ГБ в ./data. Чтобы загрузить один источник или более ранний квартал:

uv run nport-ingest land nport --period 2026q1
uv run nport-ingest land ncen --raw-only     # skip Parquet conversion
uv run nport-ingest land gleif --force       # re-download and re-convert

Related MCP server: civicgraph-mcp

Хранение

NPORT_DATA_ROOT определяет, куда всё попадает, и это единственное различие между локальной итерацией и запуском в ECS:

export NPORT_DATA_ROOT=./data                 # default
export NPORT_DATA_ROOT=s3://my-bucket/nport   # needs the `s3` extra: uv sync --extra s3

Структура, согласно docs/design.md §2:

{root}/raw/{source}/{period}/{archive}.zip             original bytes, immutable
{root}/parquet/{table}/period={period}/data.parquet     zstd, all columns VARCHAR
{root}/parquet/_manifest/{source}/period={period}/
    manifest.json    source URL, raw SHA-256, per-table row counts
    schema.json      column names, types, descriptions and PKs, from the
                     CSVW sidecar the SEC ships inside each archive

Повторный запуск для уже загруженного периода ничего не делает, если не передан --force, что делает задачу безопасной для повторного запуска по расписанию. Если SEC повторно опубликует квартал под тем же именем файла, запуск предупредит, что количество байт изменилось, а не будет молча отдавать устаревшие данные.

Проектные решения в слое приёма данных

Каждый столбец Parquet имеет тип VARCHAR. Типизация должна выполняться в dbt staging/. Источники полны значений, которые ломают вывод типов — даты вроде 28-FEB-2026, числа вроде -.0091723714 и N/A, встречающееся в числовых столбцах, — поэтому вывод типов здесь либо завершился бы ошибкой, либо молча выполнил бы приведение типов, и это поместило бы бизнес-логику в тот единственный слой, который должен оставаться воспроизводимым из исходных байтов.

URL-адреса загрузки обнаруживаются, а не конструируются. Большинство архивов SEC следуют шаблону {period}_{source}.zip, но несколько кварталов N-CEN после повторной публикации были выложены как 2025q1_ncen_0.zip. Индексная страница парсится для поиска href, а стандартный шаблон используется как запасной вариант.

Извлекаются собственные метаданные схемы архивов. Оба ZIP-архива SEC содержат CSVW *_metadata.json, в котором объявлены первичные ключи для каждой таблицы, типы столбцов и описания столбцов. Это авторитетный источник для проверок гранулярности в transform/, поэтому он сохраняется как schema.json, а не остаётся внутри ZIP.

Структура

src/nport/ingest/        fetch -> validate -> land as Parquet
    sources/             one module per upstream source
    convert.py           ZIP of delimited text -> Parquet, via DuckDB
    land.py              orchestration and manifests
    storage.py           URI addressing over fsspec (local or S3)
transform/               dbt project (dbt-duckdb)          [not built]
src/nport/server/        FastMCP server                    [not built]
evals/                   scored question set               [not built]
infra/                   Terraform                         [not built]

Разработка

uv run ruff check src/ && uv run ruff format src/
uv run pytest