nport

Normalisierte Fondsbestände und Dienstleister‑Graph, erstellt aus SEC Form N‑PORT und Form N‑CEN, verknüpft mit dem GLEIF‑LEI‑Register und über MCP für Agenten bereitgestellt.

Entwurf: docs/design.md. Empirische Anmerkungen zu den Quelldaten: docs/data‑notes.md.

Status: nur die Ingest‑Schicht. Raw‑ und Parquet‑Ebenen werden Ende‑zu‑Ende geschrieben; die dbt‑Transformation, der MCP‑Server und Terraform sind noch nicht gebaut.

Schnellstart

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

Das Laden aller drei Quellen dauert einige Minuten und schreibt ~1 GB unter ./data. Um eine einzelne Quelle oder ein älteres Quartal zu laden:

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

Speicherung

NPORT_DATA_ROOT bestimmt den Speicherort und ist der einzige Unterschied zwischen lokaler Iteration und dem Betrieb in ECS:

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

Layout gemäß 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

Das erneute Verarbeiten eines bereits gelandeten Zeitraums ist ein No‑Op, solange --force nicht gesetzt ist. Dadurch ist die Aufgabe für geplante Wiederholungen sicher. Nur falls die SEC ein Quartal unter demselben Dateinamen neu veröffentlicht, meldet der Lauf eine Warnung, dass sich die Byteanzahl geändert hat, statt still veraltete Daten auszuliefern.

Design‑Entscheidungen in der Ingest‑Schicht

Jede Parquet‑Spalte ist VARCHAR. Die Typisierung gehört in die dbt staging/. Die Datenquellen sind voller Werte, die versionstypübergreifende typerkennung verletzen – Daten wie 28-FEB-2026, Zahlen wie -.0091723714 und N/A in numerischen Spalten – deshalb würde eine Typ‑Inferenz hier entweder scheitern oder stillschweigend falsche Werte erzwingen; außerdem würde sie Geschäftslogik in genau die Schicht einfügen, die aus einer Raw‑Byte‑Reproduktion deterministisch bleiben muss.

Download‑URLs werden entdeckt, nicht konstruiert. Die meisten SEC‑Archive verwenden {period}_{source}.zip. Nach einer erneuten Veröffentlichung kamen personnes einige N‑CEN‑Quartale als 2025-A und_N-0.zip. Die Index‑Seite wird als Grundlage für diese Zeitabschnitts‑Schablone durchsucht, wobei das immer Musters als Fallback dient.

Die Schema‑Metadaten der Archive selbst werden extrahiert. Beide SEC‑ZIP-Dateien enthalten eine DB‑weit *_metadata.json, die in der jeweiligen Tabelle die Primärschlüssel, die Spaltentypen und die Spaltenbeschreibungen für G‑Asserts in transform/ beschreibt. Deshalb wird diese Metadaten als schema.json nach außen geschrieben und nicht in der ZIP belassen.

Layout

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]

Entwicklung

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