nport

Gráfico normalizado de tenencias de fondos y proveedores de servicios construido a partir de los formularios SEC Form N-PORT y Form N-CEN, unido al registro LEI de GLEIF, y servido a agentes a través de MCP.

Diseño: docs/design.md. Notas empíricas sobre los datos de origen: docs/data-notes.md.

Estado: solo capa de ingesta. Las capas raw y Parquet llegan de extremo a extremo; la transformación dbt, el servidor MCP y Terraform aún no están construidos.

Inicio rápido

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

Cargar las tres fuentes tarda unos minutos y escribe ~1 GB en ./data. Para cargar una sola fuente o un trimestre anterior:

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

Almacenamiento

NPORT_DATA_ROOT controla dónde va todo y es la única diferencia entre la iteración local y la ejecución en ECS:

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

Distribución, según 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

Volver a ejecutar un período ya cargado no hace nada a menos que se pase --force, lo que hace que la tarea sea segura de reintentar desde una programación. Si la SEC republica un trimestre con el mismo nombre de archivo, la ejecución advierte que el recuento de bytes cambió en lugar de servir silenciosamente datos obsoletos.

Decisiones de diseño en la capa de ingesta

Cada columna de Parquet es VARCHAR. El tipado pertenece a dbt staging/. Las fuentes están llenas de valores que rompen la inferencia de tipos — fechas como 28-FEB-2026, números como -.0091723714 y N/A que aparece en columnas numéricas — por lo que la inferencia aquí fallaría o coercionaría silenciosamente, y pondría lógica de negocio en la única capa que debe permanecer reproducible a partir de bytes crudos.

Las URL de descarga se descubren, no se construyen. La mayoría de los archivos SEC siguen {period}_{source}.zip, pero varios trimestres de N-CEN se publicaron como 2025q1_ncen_0.zip después de una republicación. La página de índice se analiza en busca de hrefs, con el patrón convencional como respaldo.

Se extraen los metadatos de esquema de los propios archivos. Ambos ZIP de SEC contienen un *_metadata.json de CSVW que declara claves primarias por tabla, tipos de columna y descripciones de columna. Ese es el insumo autoritativo para las aserciones de granularidad en transform/, por lo que se escribe como schema.json en lugar de dejarlo en un ZIP.

Distribución

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]

Desarrollo

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