Point-in-time screener and dataset catalog¶
P4 adds three read-only data-layer capabilities: universe_screen,
dataset_catalog, and point_in_time_dataset_export. They share the same
point-in-time row selection and governance rules across CLI, MCP, and REST.
universe_screen and point_in_time_dataset_export are advanced tools and
dataset_catalog is a diagnostic tool. Each needs an explicit grant and none is
a consumer tool.
Declarative screening¶
The screener accepts only a closed predicate structure: field, operator, and
typed value. Fields come from an allowlist; operators are eq, ne, lt,
lte, gt, gte, and in. Unknown fields, mismatched values, missing field
scopes, disallowed providers, and scans above 10,000 candidate rows fail before
results are returned. License exclusions apply when server license enforcement
is enabled; the default disabled mode preserves license metadata.
Date predicates use ISO dates (YYYY-MM-DD). Datetime predicates must include
a UTC offset, for example 2024-06-28T20:00:00Z. Numeric predicates require
finite numbers. Invalid predicates are rejected even when no source rows exist.
Reuse the returned cursor verbatim; malformed cursors return invalid_argument.
Sorting is deterministic. security_id and session_date are implicit final
tie-breakers, and cursors are bound to the canonical query hash. A cursor cannot
be reused with changed filters. Results contain canonical conditions, records,
reproducible fields, counts, and cost units. They contain no score,
recommendation, selection judgment, or ranking explanation.
argus universe-screen \
--api-key "$ARGUS_MACHINE_API_KEY" \
--as-of 2024-07-01T00:00:00Z \
--filters-json '[{"field":"market_cap","operator":"gte","value":800000000}]' \
--select security_id,ticker,market_cap
Point-in-time abstractions¶
- Calendar records bind a session and calendar version to
effective_atandknown_at. - Instrument records use permanent
security_id, effective security lifetime, ticker/MIC mapping, listing status, provider, and license. - Feature records are append-only revisions keyed by feature/security/session;
the visible revision is the last one with
effective_at <= as_ofandknown_at <= as_of. - Prepared row selection applies the allowed-provider set to both instruments
and features before choosing revisions. A returned row's
known_atis the later of the identity mapping and feature capture times. Conflicting values at the latest visible revision and known time require source reconciliation; input order does not select a winner. A later visible correction supersedes an older conflict. These rules also apply to export rows and do not establish a production historical universe or source coverage. - Dataset definitions publish primary keys, partition fields, field types, providers, supported formats, and PIT/revision guarantees.
Historical universes are reconstructed from the relevant lifetime and mapping;
they are not joined to today's active-security list. The public bindings include
delisted securities by default. To exclude them, add an allowlisted predicate
{"field":"listing_status","operator":"ne","value":"delisted"}. The internal
UniverseDefinition.include_delisted setting is not a public request parameter.
Production coverage¶
The point_in_time_snapshot reader (point-in-time-db-v2) returns persisted
filing financial facts, preserving each fact's period, unit, currency,
dimensions, exact numeric representation and source evidence. It selects the
latest visible revision of each financial aspect. A document must have been
published and captured by as_of; the fact's known, created and revision times
must also be at or before that cutoff. Capturing an old filing today does not
make its facts visible in a query for yesterday.
snapshot.known_at is metadata containing the requested cutoff;
snapshot.record_count counts the selected financial facts, excluding the
metadata itself. Both metadata facts reference all contributing source evidence
and license scopes. Missing actual facts produce an empty result without
fabricated metadata. Historical captures without recorded license terms retain
unknown license status; they become partial for that gap only when server license
enforcement is enabled. Missing any supported financial field (revenue,
net_income, operating_cash_flow, total_assets, total_liabilities) is
reported as partial with a financial_field:<name> coverage gap; missing
observations are never replaced by derived or invented supplier values.
Actual persisted coverage still decides which companies, fields and periods
are complete; the reader does not establish complete company, field or
historical coverage by itself.
The built-in PIT repository is a local contract fixture. Production binds the
same contract to persisted rows: instruments come from the official security
master (only captures whose mounted source license resolves are projected) and
features come from persisted daily market bar observations. Providers and
values a source does not establish (for example market capitalization or a
split-adjusted close) remain absent with that absence disclosed by the reader
and by the Arrow schema nullability; nothing is inferred from the raw close.
dataset_catalog describes the supported schema, export formats, and the
mounted provider ids; its presence does not by itself prove data availability
for a specific subject or period.
Reproducible exports¶
point_in_time_dataset_export writes deterministic Arrow IPC or Parquet
partitions. Its manifest contains the dataset identity, schema fingerprint,
partition values and object keys, per-partition byte length and SHA-256, aggregate
content hash, time window, provider, license, adjustment policy, and canonical
parameters.
The cache key always covers tenant, tool version, schema version, provider,
as_of, license policy, adjustment policy, and canonical parameters. Repeating
an identical request over identical source revisions yields the same partition
bytes, manifest values, content hash, and dataset identity.
This point-in-time export does not calculate returns, performance, signals, portfolios, or strategy conclusions. Major-version migration history is available only as structured Registry metadata.