neutral_trade.metrics

Documentation for eth_defi.neutral_trade.metrics Python module.

Resumable Neutral Trade directory, backfill and live collection.

All modes share one page reader and transactional, single-owner DuckDB writer. API contracts: https://api.neutral.trade/openapi.json.

Module Attributes

MAX_RAW_AMOUNT_DIGITS

Bounds untrusted integer strings while accommodating EVM uint256 amounts.

Functions

fetch_history_page(api_key, vault, endpoint, ...)

Fetch one page in an isolated worker session without database access.

run_scan(db, api_key, *[, max_workers, ...])

Discover leads, refresh current metadata and resume bounded history.

Classes

NeutralTradeDatabase

Own one private source archive and exclusive source writer lock.

ScanResult

Observe completed work separately from incomplete maintenance.

MAX_RAW_AMOUNT_DIGITS = 128

Bounds untrusted integer strings while accommodating EVM uint256 amounts.

class ScanResult

Bases: object

Observe completed work separately from incomplete maintenance.

leads: int

Available catalogue records, before explicit selection.

pages: int

Committed history pages.

failures: int

Operations which failed and remain due.

pending: bool

True when the page/time budget leaves work for a later invocation.

__init__(leads=0, pages=0, failures=0, pending=False)
Parameters
  • leads (int) –

  • pages (int) –

  • failures (int) –

  • pending (bool) –

Return type

None

class NeutralTradeDatabase

Bases: object

Own one private source archive and exclusive source writer lock.

Unconstrained tables avoid DuckDB ART-index corruption. Raw observations and progress are committed together, preserving all unmatched history. Workers never access this connection.

Parameters

path – Explicit private source archive, not a public dataset.

Acquire ownership before opening the file-backed database.

The entry-point must already hold lifecycle/pipeline locks where needed.

Parameters

path – File-backed source database.

__init__(path)

Acquire ownership before opening the file-backed database.

The entry-point must already hold lifecycle/pipeline locks where needed.

Parameters

path (pathlib.Path) – File-backed source database.

Return type

None

save_lead(vault, metrics=None)

Upsert current metadata without deleting disappeared leads.

WSOL retains only a minimal exclusion audit, with no detailed data. A metadata refresh preserves previous metrics until replaced.

Parameters
Returns

None.

Return type

None

prepare_history(vault, endpoint, *, start_date, end_date, refresh=False)

Resume incomplete work or open a bounded incremental date range.

Completed histories refresh daily with a seven-day correction overlap; new leads and explicit refresh/range requests are immediately due.

Parameters
Returns

Whether a page is due.

Return type

bool

history_request(vault, endpoint)

Read the current persisted page position.

The range stays fixed across resumptions; its cursor is opaque.

Parameters
Returns

Cursor, start date and end date.

Return type

tuple[str | None, datetime.date | None, datetime.date]

save_page(vault, endpoint, page)

Atomically store one validated page and its continuation cursor.

Full source JSON preserves exact values and provenance. Corrections replace the same event key; shortened responses never delete history.

Parameters
Returns

True when this range reached its terminal cursor.

Return type

bool

record_error(vault, endpoint, error)

Keep failed work due without changing cursor/coverage.

Only sanitised client diagnostics should be supplied by callers.

Parameters
Returns

None.

Return type

None

iter_leads()

Yield retained source metadata, including unavailable decisions.

This is a private archive API; public exporters apply admission checks.

Returns

Lead dictionaries with raw configuration and metrics.

Return type

collections.abc.Iterator[dict]

fetch_history_page(api_key, vault, endpoint, position)

Fetch one page in an isolated worker session without database access.

Workers return parsed values; the owner commits pages as results arrive.

Parameters
Returns

Identity, endpoint, page or sanitised error.

Return type

tuple[eth_defi.neutral_trade.api.NeutralTradeVault, str, dict | None, str | None]

run_scan(db, api_key, *, max_workers=2, page_budget=100, time_budget=300, vault_ids=None, start_date=None, end_date=None, refresh=False)

Discover leads, refresh current metadata and resume bounded history.

Manual/full and scheduled/incremental modes use this same routine. Daily histories use independent eligibility; current metrics refresh every run.

Parameters
  • db (eth_defi.neutral_trade.metrics.NeutralTradeDatabase) – Owner-thread private database under its source lock.

  • api_key (str) – Partner credential.

  • max_workers (int) – Threaded page-reader concurrency.

  • page_budget (int) – Maximum committed/attempted pages this invocation.

  • time_budget (float) – Time before stopping new page dispatches.

  • vault_ids (Optional[set[str]]) – Optional exact source IDs; exclusions still apply.

  • start_date (Optional[datetime.date]) – Optional inclusive historical start.

  • end_date (Optional[datetime.date]) – Optional fixed end, default today in UTC.

  • refresh (bool) – Reopen completed histories for a full refresh.

Returns

Counts distinguishing failures, pending work and completion.

Return type

eth_defi.neutral_trade.metrics.ScanResult