xfinlink 0.1.1__tar.gz

xfinlink-0.1.1/CLAUDE.md

@@ -0,0 +1,121 @@
+# xfinlink — guidance for AI agents
+
+xfinlink is a local entity-resolution tool for financial data. It answers one
+question: **"which economic entity does this identifier refer to, and what
+other identifiers does that same entity have?"** It ships five MCP tools
+(`resolve_identifier`, `bulk_resolve`, `entity_lineage`, `search_entity`,
+`validate_identifiers`), a Python API, a CLI, and a local HTTP server — all
+backed by the same Postgres crosswalk database built from CRSP, Compustat,
+IBES, and SEC EDGAR.
+
+If you are reasoning about a dataset that mixes any of the following
+identifiers, you should be using xfinlink:
+
+- **PERMNO / PERMCO** — CRSP (market data: prices, returns, volume)
+- **GVKEY** — Compustat (fundamentals: balance sheet, income statement)
+- **CIK** — SEC EDGAR (filings: 10-K, 10-Q, 8-K, 13F)
+- **CUSIP (8 or 9)** — bond/equity master files
+- **Ticker** — market data vendors (Yahoo, Bloomberg, yfinance, FRED)
+- **ISIN / IBES ticker / FIGI** — international, analyst estimates, OpenFIGI
+
+## Why this matters: the ticker-recycling problem
+
+Tickers are not stable identifiers. They get retired, reissued, and reused
+across companies that have nothing to do with each other. A naive
+ticker-based merge across databases silently stitches unrelated entities into
+one row-group and corrupts downstream analysis. **Nearly 10,000 tickers in
+the CRSP universe map to more than one distinct entity over time.** A few
+high-salience examples:
+
+- **GM** — Before June 2009, "GM" was General Motors Corporation (PERMNO
+  12079). The company filed Chapter 11 on 2009-06-01. "Old GM" was delisted
+  and eventually wound down. On 2010-11-18, an entirely new company, General
+  Motors Company (PERMNO 12369), IPO'd out of the bankruptcy and took the
+  "GM" ticker. They share the same GVKEY (005073) because Compustat models
+  the economic continuation, but they have different PERMNOs because CRSP
+  treats them as legally distinct securities. A panel keyed on ticker "GM"
+  across 2005-2024 is a silent 50/50 mixture of two different companies.
+- **FB** — Belonged to Meta Platforms Inc until the 2022 rebrand to META.
+  Historically the "FB" ticker has also been used by PROSHARES, FBR Capital,
+  BankBoston, and Falcon Building Products. Resolving "FB" without a date
+  returns five matches.
+- **META** — The ticker was used by another company before Meta adopted it
+  in 2022.
+- **INGR** — Recycled multiple times across unrelated corporations over the
+  decades.
+
+When you see ambiguous=true from `resolve_identifier`, treat it as a
+disambiguation prompt — either pass `as_of_date`, or call `entity_lineage`
+to understand the family tree.
+
+## Which tool to use when
+
+- **You have an id_value and need the entity (and all its other ids):**
+  `resolve_identifier`. Pass `as_of_date` if the data is time-series.
+- **You have many ids to resolve in one shot:** `bulk_resolve` (max 100).
+- **You have a company name but no id:** `search_entity` → pick a result →
+  `resolve_identifier` on one of its PERMNO/GVKEY values for the full record.
+- **You have a merged panel and want to audit it:** `validate_identifiers`.
+  Run it AFTER merging. Any `wrong_entity` flag means your panel has stitched
+  different companies under one ticker.
+- **You need to understand a company's corporate history:** `entity_lineage`.
+  Walks the predecessor/successor graph across bankruptcies, mergers,
+  spinoffs, name changes, and ticker changes.
+
+## Canonical merge keys
+
+Once you have a resolution, **prefer PERMNO or GVKEY as the merge key** in
+downstream joins. Both are permanent identifiers issued by data vendors that
+survive ticker changes, reorganizations, and most corporate events. Tickers
+are display values, not keys. CIKs are keys for SEC filings but are not
+always unique across subsidiaries and parents.
+
+In order of preference for panel construction:
+
+1. **GVKEY** — most stable for economic-continuation analysis (survives
+   bankruptcies where the business continues).
+2. **PERMNO** — most precise for market-data analysis (distinguishes the
+   pre- and post-bankruptcy security, which GVKEY does not).
+3. **CIK** — use for SEC filings. Not recommended as the primary merge key
+   because a single parent filer can cover multiple economic entities.
+4. **CUSIP (9)** — useful for bond/equity-level joins but changes on some
+   corporate actions.
+5. **Ticker** — display only. Never the merge key.
+
+## Historical resolution
+
+Almost every financial dataset is a panel. `as_of_date` is the most
+important parameter in xfinlink. Use YYYY-MM-DD format. The resolver applies
+the temporal filter `valid_from <= as_of_date <= valid_to` against each
+identifier's validity window, with NULL treated as "open-ended."
+
+If a user asks "who is AAPL?" without a date, that's probably fine (AAPL has
+been Apple Inc since 1980). If they ask "what was FB's GVKEY in 2019?", use
+`as_of_date="2019-01-01"` to avoid the 5-way ambiguity.
+
+## Validation workflow
+
+The canonical ticker-recycling bug hides in silence: the merge succeeds, the
+DataFrame has the right number of rows, the regression runs, and the results
+are quietly wrong. The defense is to run `validate_identifiers` on every
+panel before trusting it.
+
+```
+validate_identifiers(identifiers='[{"id_type":"ticker","id_value":"GM","date":"2006-01-01"}, {"id_type":"ticker","id_value":"GM","date":"2022-01-01"}]')
+```
+
+If `is_clean` is false and the issues include `wrong_entity`, re-key on
+PERMNO or GVKEY and re-merge. The `coverage` dict shows you which canonical
+entities the panel actually matched and their row counts, so a stitched GM
+panel will read `{"General Motors Corporation (pre-2009 bankruptcy)": 4,
+"General Motors Company": 6}` — a 50/50 breakdown that's an unmistakable
+signal of the problem.
+
+## Non-goals
+
+- xfinlink does not serve market data, prices, fundamentals, or filings. It
+  is a crosswalk, not a data provider.
+- xfinlink does not guess. If `not_found` is true, the identifier genuinely
+  is not in the crosswalk — do not fabricate a match.
+- xfinlink does not resolve private companies, funds, or non-US entities
+  outside what CRSP / Compustat / EDGAR cover.

xfinlink-0.1.1/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include CLAUDE.md
+recursive-exclude tests *
+recursive-exclude data *
+recursive-exclude scripts *
+global-exclude __pycache__
+global-exclude *.pyc

xfinlink-0.1.1/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: xfinlink
+Version: 0.1.1
+Summary: Financial entity identifier resolution — resolve, validate, and fix PERMNO/GVKEY/CIK/CUSIP/ticker/ISIN mappings across CRSP, Compustat, EDGAR, and more.
+Author: xfinlink
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://xfinlink.io
+Project-URL: Documentation, https://xfinlink.io/docs
+Keywords: finance,CRSP,Compustat,EDGAR,PERMNO,GVKEY,CUSIP,ticker,identifier,resolver
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pandas
+Requires-Dist: pyarrow
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: psycopg2-binary
+Requires-Dist: asyncpg
+Requires-Dist: greenlet
+Requires-Dist: fastapi
+Requires-Dist: uvicorn
+Requires-Dist: httpx
+Requires-Dist: alembic
+Requires-Dist: pydantic
+Requires-Dist: python-dotenv
+Requires-Dist: typer[all]
+Requires-Dist: mcp
+Provides-Extra: wrds
+Requires-Dist: wrds; extra == "wrds"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+
+# xfinlink
+
+Financial entity identifier resolution. Resolve, validate, and fix identifier mappings across CRSP, Compustat, SEC EDGAR, IBES, and more.
+
+## The problem
+
+Financial data is spread across databases that use different identifiers. CRSP uses PERMNOs. Compustat uses GVKEYs. SEC EDGAR uses CIKs. Markets use tickers. Tickers get recycled — GM before 2009 (General Motors Corporation) and GM after 2010 (General Motors Company) are legally distinct entities that happen to share a ticker. A naive merge silently produces wrong data.
+
+Nearly 10,000 tickers in the CRSP universe map to more than one distinct entity over time. The bug hides in silence: the merge succeeds, the DataFrame has the right number of rows, the regression runs, and the results are quietly wrong.
+
+## What xfinlink does
+
+- **Resolve** — any identifier → all other identifiers for the same entity, correctly matched at any point in time
+- **Validate** — audit a merged panel and flag silent identifier errors (ticker recycling, outside-validity dates, ambiguous matches)
+- **Fix** — return a corrected DataFrame with proper per-row entity, PERMNO, GVKEY, and CIK columns
+
+## Install
+
+```bash
+pip install xfinlink
+```
+
+WRDS ingestion is optional:
+
+```bash
+pip install "xfinlink[wrds]"
+```
+
+## Quick start
+
+```bash
+xfinlink init                              # start postgres + run migrations
+xfinlink build                             # ingest EDGAR (public)
+xfinlink build --wrds                      # optional: add CRSP/Compustat/IBES
+
+xfinlink status                            # DB census + identifier coverage
+xfinlink resolve ticker AAPL               # → Apple Inc with all linked ids
+xfinlink resolve ticker GM --date 2008-01-01
+                                           # → General Motors Corporation (pre-bankruptcy)
+xfinlink resolve ticker GM --date 2020-01-01
+                                           # → General Motors Company (post-bankruptcy)
+
+xfinlink validate panel.csv --id-column ticker --date-column date
+                                           # → flags stitched/ambiguous/not-found rows
+xfinlink fix      panel.csv --id-column ticker --date-column date
+                                           # → writes panel_fixed.csv with per-row PERMNO/GVKEY/CIK
+
+xfinlink serve                             # local HTTP API on http://localhost:8000
+xfinlink mcp                               # MCP server for AI agents
+```
+
+Example — catching the GM stitching bug:
+
+```
+$ xfinlink validate gm_panel.csv --id-column ticker --date-column date
+10 rows checked. 0 clean. 10 issues found.
+┏━ Coverage (entity → row count) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ canonical_name                                          rows ┃
+┃ General Motors Corporation (pre-2009 bankruptcy)           5 ┃
+┃ General Motors Company                                     5 ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+Issues written to xfinlink_validation_report.csv
+```
+
+## Python API
+
+```python
+from xfinlink import resolve, bulk_resolve, search_entities, get_lineage
+from xfinlink import validate_dataframe, fix_dataframe
+
+# Single resolve, with optional historical date
+r = resolve("ticker", "AAPL")
+r = resolve("ticker", "GM", as_of_date="2008-01-01")
+
+# Batch resolve
+results = bulk_resolve([
+    {"id_type": "ticker", "id_value": "AAPL"},
+    {"id_type": "gvkey",  "id_value": "001690"},
+    {"id_type": "cik",    "id_value": "0000320193"},
+])
+
+# Panel validation — the headline feature
+import pandas as pd
+df = pd.read_csv("gm_panel.csv")
+report = validate_dataframe(df, "ticker", date_column="date")
+if not report.is_clean:
+    print(report.summary)
+    print(report.coverage)      # {"General Motors Corporation (pre-2009 bankruptcy)": 5, ...}
+    fixed = fix_dataframe(df, "ticker", date_column="date")
+    # fixed["_permno"], fixed["_gvkey"], fixed["_cik"], fixed["_xfinlink_flag"]
+```
+
+## For AI agents
+
+```bash
+xfinlink mcp    # start the MCP server over stdio
+```
+
+xfinlink exposes five MCP tools — `resolve_identifier`, `bulk_resolve`, `entity_lineage`, `search_entity`, `validate_identifiers` — connected directly to the local crosswalk database. See [CLAUDE.md](CLAUDE.md) for tool descriptions, the GM/FB/META disambiguation cases, and guidance on when to use each tool.
+
+## Local HTTP server
+
+```bash
+xfinlink serve --port 8000
+```
+
+Endpoints:
+
+| Method | Path | Purpose |
+|---|---|---|
+| POST | /v1/resolve | single identifier resolution |
+| POST | /v1/resolve/bulk | batch resolution (max 1000) |
+| GET  | /v1/lineage/{entity_id} | corporate event history |
+| GET  | /v1/search?q=...&limit=... | name search |
+| POST | /v1/validate | panel validation |
+| GET  | /v1/health | DB stats |
+
+Interactive docs at http://localhost:8000/docs.
+
+## Data sources
+
+- **Without WRDS:** CIK, ticker, CUSIP (SEC EDGAR), ISIN, FIGI (OpenFIGI).
+- **With WRDS:** adds PERMNO, GVKEY, IBES ticker, and the CCM linking table, plus corporate event detection (bankruptcy / relisting pairs).
+
+## Legal
+
+xfinlink does not redistribute any proprietary data. When you run `xfinlink build --wrds`, it connects to **your** WRDS account and builds the crosswalk locally from data you are licensed to access. The pip package contains only source code — no CRSP, Compustat, IBES, or EDGAR data is shipped.
+
+## License
+
+xfinlink is distributed under a commercial license with a trial mode: 500 resolutions per session, all features available. Get a license key at https://xfinlink.io and drop it in `~/.xfinlink/license.key` to remove the trial limit.

xfinlink-0.1.1/README.md

@@ -0,0 +1,131 @@
+# xfinlink
+
+Financial entity identifier resolution. Resolve, validate, and fix identifier mappings across CRSP, Compustat, SEC EDGAR, IBES, and more.
+
+## The problem
+
+Financial data is spread across databases that use different identifiers. CRSP uses PERMNOs. Compustat uses GVKEYs. SEC EDGAR uses CIKs. Markets use tickers. Tickers get recycled — GM before 2009 (General Motors Corporation) and GM after 2010 (General Motors Company) are legally distinct entities that happen to share a ticker. A naive merge silently produces wrong data.
+
+Nearly 10,000 tickers in the CRSP universe map to more than one distinct entity over time. The bug hides in silence: the merge succeeds, the DataFrame has the right number of rows, the regression runs, and the results are quietly wrong.
+
+## What xfinlink does
+
+- **Resolve** — any identifier → all other identifiers for the same entity, correctly matched at any point in time
+- **Validate** — audit a merged panel and flag silent identifier errors (ticker recycling, outside-validity dates, ambiguous matches)
+- **Fix** — return a corrected DataFrame with proper per-row entity, PERMNO, GVKEY, and CIK columns
+
+## Install
+
+```bash
+pip install xfinlink
+```
+
+WRDS ingestion is optional:
+
+```bash
+pip install "xfinlink[wrds]"
+```
+
+## Quick start
+
+```bash
+xfinlink init                              # start postgres + run migrations
+xfinlink build                             # ingest EDGAR (public)
+xfinlink build --wrds                      # optional: add CRSP/Compustat/IBES
+
+xfinlink status                            # DB census + identifier coverage
+xfinlink resolve ticker AAPL               # → Apple Inc with all linked ids
+xfinlink resolve ticker GM --date 2008-01-01
+                                           # → General Motors Corporation (pre-bankruptcy)
+xfinlink resolve ticker GM --date 2020-01-01
+                                           # → General Motors Company (post-bankruptcy)
+
+xfinlink validate panel.csv --id-column ticker --date-column date
+                                           # → flags stitched/ambiguous/not-found rows
+xfinlink fix      panel.csv --id-column ticker --date-column date
+                                           # → writes panel_fixed.csv with per-row PERMNO/GVKEY/CIK
+
+xfinlink serve                             # local HTTP API on http://localhost:8000
+xfinlink mcp                               # MCP server for AI agents
+```
+
+Example — catching the GM stitching bug:
+
+```
+$ xfinlink validate gm_panel.csv --id-column ticker --date-column date
+10 rows checked. 0 clean. 10 issues found.
+┏━ Coverage (entity → row count) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ canonical_name                                          rows ┃
+┃ General Motors Corporation (pre-2009 bankruptcy)           5 ┃
+┃ General Motors Company                                     5 ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+Issues written to xfinlink_validation_report.csv
+```
+
+## Python API
+
+```python
+from xfinlink import resolve, bulk_resolve, search_entities, get_lineage
+from xfinlink import validate_dataframe, fix_dataframe
+
+# Single resolve, with optional historical date
+r = resolve("ticker", "AAPL")
+r = resolve("ticker", "GM", as_of_date="2008-01-01")
+
+# Batch resolve
+results = bulk_resolve([
+    {"id_type": "ticker", "id_value": "AAPL"},
+    {"id_type": "gvkey",  "id_value": "001690"},
+    {"id_type": "cik",    "id_value": "0000320193"},
+])
+
+# Panel validation — the headline feature
+import pandas as pd
+df = pd.read_csv("gm_panel.csv")
+report = validate_dataframe(df, "ticker", date_column="date")
+if not report.is_clean:
+    print(report.summary)
+    print(report.coverage)      # {"General Motors Corporation (pre-2009 bankruptcy)": 5, ...}
+    fixed = fix_dataframe(df, "ticker", date_column="date")
+    # fixed["_permno"], fixed["_gvkey"], fixed["_cik"], fixed["_xfinlink_flag"]
+```
+
+## For AI agents
+
+```bash
+xfinlink mcp    # start the MCP server over stdio
+```
+
+xfinlink exposes five MCP tools — `resolve_identifier`, `bulk_resolve`, `entity_lineage`, `search_entity`, `validate_identifiers` — connected directly to the local crosswalk database. See [CLAUDE.md](CLAUDE.md) for tool descriptions, the GM/FB/META disambiguation cases, and guidance on when to use each tool.
+
+## Local HTTP server
+
+```bash
+xfinlink serve --port 8000
+```
+
+Endpoints:
+
+| Method | Path | Purpose |
+|---|---|---|
+| POST | /v1/resolve | single identifier resolution |
+| POST | /v1/resolve/bulk | batch resolution (max 1000) |
+| GET  | /v1/lineage/{entity_id} | corporate event history |
+| GET  | /v1/search?q=...&limit=... | name search |
+| POST | /v1/validate | panel validation |
+| GET  | /v1/health | DB stats |
+
+Interactive docs at http://localhost:8000/docs.
+
+## Data sources
+
+- **Without WRDS:** CIK, ticker, CUSIP (SEC EDGAR), ISIN, FIGI (OpenFIGI).
+- **With WRDS:** adds PERMNO, GVKEY, IBES ticker, and the CCM linking table, plus corporate event detection (bankruptcy / relisting pairs).
+
+## Legal
+
+xfinlink does not redistribute any proprietary data. When you run `xfinlink build --wrds`, it connects to **your** WRDS account and builds the crosswalk locally from data you are licensed to access. The pip package contains only source code — no CRSP, Compustat, IBES, or EDGAR data is shipped.
+
+## License
+
+xfinlink is distributed under a commercial license with a trial mode: 500 resolutions per session, all features available. Get a license key at https://xfinlink.io and drop it in `~/.xfinlink/license.key` to remove the trial limit.

xfinlink-0.1.1/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "xfinlink"
+version = "0.1.1"
+description = "Financial entity identifier resolution — resolve, validate, and fix PERMNO/GVKEY/CIK/CUSIP/ticker/ISIN mappings across CRSP, Compustat, EDGAR, and more."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{name = "xfinlink"}]
+license = "LicenseRef-Proprietary"
+keywords = ["finance", "CRSP", "Compustat", "EDGAR", "PERMNO", "GVKEY", "CUSIP", "ticker", "identifier", "resolver"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial",
+]
+dependencies = [
+    "pandas",
+    "pyarrow",
+    "sqlalchemy>=2.0",
+    "psycopg2-binary",
+    "asyncpg",
+    "greenlet",
+    "fastapi",
+    "uvicorn",
+    "httpx",
+    "alembic",
+    "pydantic",
+    "python-dotenv",
+    "typer[all]",
+    "mcp",
+]
+
+[project.optional-dependencies]
+wrds = ["wrds"]
+dev = ["pytest", "pytest-asyncio"]
+
+[project.urls]
+Homepage = "https://xfinlink.io"
+Documentation = "https://xfinlink.io/docs"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project.scripts]
+xfinlink = "xfinlink.cli:app"
+
+[tool.setuptools.packages.find]
+include = ["xfinlink*"]
+exclude = ["tests*", "data*", "scripts*"]
+
+[tool.setuptools.package-data]
+xfinlink = [
+    "py.typed",
+    "alembic.ini",
+    "migrations/*.py",
+    "migrations/*.mako",
+    "migrations/README",
+    "migrations/versions/*.py",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

xfinlink-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xfinlink-0.1.1/xfinlink/__init__.py

@@ -0,0 +1,129 @@
+"""xfinlink — financial entity identifier resolution.
+
+Public Python API. Synchronous wrappers around the async resolver so
+callers do not have to manage event loops or database sessions.
+
+    from xfinlink import resolve, bulk_resolve, search_entities, get_lineage
+
+    r = resolve("ticker", "AAPL")
+    r = resolve("ticker", "GM", as_of_date="2008-01-01")
+    results = bulk_resolve([{"id_type": "ticker", "id_value": "AAPL"}, ...])
+    hits = search_entities("General Motors")
+    lineage = get_lineage("ticker", "GM")
+"""
+from __future__ import annotations
+
+import asyncio
+from datetime import date, datetime
+from typing import Any
+
+from xfinlink._db_check import check_db_ready as _check_db_ready
+from xfinlink.db import AsyncSessionLocal
+from xfinlink.panel import ValidationReport, fix_dataframe, validate_dataframe
+from xfinlink.resolver import core as _core
+from xfinlink.resolver.core import (
+    EntityLineage,
+    LineageEvent,
+    ResolutionResult,
+    ResolvedEntity,
+    ResolvedIdentifier,
+)
+
+__all__ = [
+    "resolve",
+    "bulk_resolve",
+    "search_entities",
+    "get_lineage",
+    "validate_dataframe",
+    "fix_dataframe",
+    "ValidationReport",
+    "ResolutionResult",
+    "ResolvedEntity",
+    "ResolvedIdentifier",
+    "EntityLineage",
+    "LineageEvent",
+]
+
+
+def _to_date(value: Any) -> date | None:
+    if value is None or isinstance(value, date) and not isinstance(value, datetime):
+        return value
+    if isinstance(value, datetime):
+        return value.date()
+    if isinstance(value, str):
+        return datetime.strptime(value, "%Y-%m-%d").date()
+    raise TypeError(f"unsupported date type: {type(value).__name__}")
+
+
+def _run(coro):
+    return asyncio.run(coro)
+
+
+def resolve(
+    id_type: str,
+    id_value: str,
+    as_of_date: str | date | None = None,
+) -> ResolutionResult:
+    """Resolve a single identifier to its entity."""
+    _check_db_ready()
+    as_of = _to_date(as_of_date)
+
+    async def _inner() -> ResolutionResult:
+        async with AsyncSessionLocal() as session:
+            return await _core.resolve(session, id_type, id_value, as_of)
+
+    return _run(_inner())
+
+
+def bulk_resolve(requests: list[dict]) -> list[ResolutionResult]:
+    """Resolve a batch of identifier requests."""
+    _check_db_ready()
+    normalized: list[dict] = []
+    for req in requests:
+        r = dict(req)
+        if "as_of_date" in r:
+            r["as_of_date"] = _to_date(r["as_of_date"])
+        normalized.append(r)
+
+    async def _inner() -> list[ResolutionResult]:
+        async with AsyncSessionLocal() as session:
+            return await _core.bulk_resolve(session, normalized)
+
+    return _run(_inner())
+
+
+def search_entities(query: str, limit: int = 10) -> list[ResolvedEntity]:
+    """Fuzzy-search entities by canonical name."""
+    _check_db_ready()
+
+    async def _inner() -> list[ResolvedEntity]:
+        async with AsyncSessionLocal() as session:
+            return await _core.search_entities(session, query, limit=limit)
+
+    return _run(_inner())
+
+
+def get_lineage(
+    id_type: str,
+    id_value: str,
+    as_of_date: str | date | None = None,
+) -> EntityLineage | None:
+    """Return the corporate lineage for the entity matching an identifier.
+
+    Resolves `(id_type, id_value)` first, then returns the lineage starting
+    from the top-ranked match. The async traversal walks ticker-siblings,
+    so both sides of bankruptcy/relisting pairs end up in one lineage
+    regardless of which match is used as the seed. Returns None if the
+    identifier did not match any entity.
+    """
+    _check_db_ready()
+    as_of = _to_date(as_of_date)
+
+    async def _inner() -> EntityLineage | None:
+        async with AsyncSessionLocal() as session:
+            result = await _core.resolve(session, id_type, id_value, as_of)
+            if result.not_found:
+                return None
+            return await _core.get_lineage(session, result.matches[0].entity_id)
+
+    return _run(_inner())

xfinlink-0.1.1/xfinlink/_db_check.py

@@ -0,0 +1,23 @@
+"""Shared DB-readiness check used by the public API and panel module."""
+from __future__ import annotations
+
+from sqlalchemy import func, select
+from sqlalchemy.exc import OperationalError
+
+from xfinlink.db import SessionLocal
+from xfinlink.models import Entity
+
+_DB_ERROR = (
+    "Database not found or empty. "
+    "Run `xfinlink init && xfinlink build` first."
+)
+
+
+def check_db_ready() -> None:
+    try:
+        with SessionLocal() as s:
+            n = s.scalar(select(func.count()).select_from(Entity))
+    except OperationalError as exc:
+        raise RuntimeError(_DB_ERROR) from exc
+    if not n:
+        raise RuntimeError(_DB_ERROR)