core.typedshims
core.typedshims
Boundary wrappers for untyped third-party surfaces (type-system-as-core-audit.md §2.5).
One module per dependency without py.typed (V2, 2026-07-11: lancedb,
sknetwork, psutil). Core imports the shim, never the raw package, so the
Any an untyped import launders is quarantined to exactly one file per
dependency instead of smeared through the checked region. Every raw import here
carries a per-line warranted ignore — the pyproject ignore_missing_imports
override no longer covers these packages.
Discipline: a shim exposes the minimal typed surface core actually calls, with
no explicit Any anywhere (falsifier: disallow_any_explicit spot-check).
Widen a Protocol only together with the new call that needs it.
lancedb
Typed facade over lancedb (type-system-as-core-audit.md §2.5 boundary wrapper).
lancedb ships no py.typed (V2, 2026-07-11), so a raw import launders Any
through every downstream call. This module is the ONE place core touches the raw
package: values coming back from lancedb are pinned to the minimal Protocol
surface the vector store actually uses, so the checked region sees honest types.
Compute/storage-only dependency — embedded, no daemon, no network (Invariant 2).
Do not widen these Protocols speculatively: they describe what core calls today, and each addition should arrive with the call that needs it.
Row = dict[str, object]
module-attribute
ArrowTable
Bases: Protocol
The slice of pyarrow.Table the store consumes from to_arrow().
to_pylist()
TableNames
Bases: Protocol
Result of list_tables() — we read only the name list.
tables
instance-attribute
VectorQuery
Bases: Protocol
LanceDB's chained query builder, as used by VectorStore.search.
metric(name)
where(predicate, *, prefilter=...)
limit(k)
to_list()
VectorTable
Bases: Protocol
The slice of a LanceDB table the store calls.
add(rows)
count_rows()
delete(predicate)
to_arrow()
search(vector)
VectorDB
Bases: Protocol
The slice of a LanceDB connection the store calls.
list_tables()
open_table(name)
create_table(name, *, schema)
drop_table(name)
connect(uri)
Open/create an embedded LanceDB at uri — the sole typed entry point.
psutil
Typed facade over psutil (type-system-as-core-audit.md §2.5 boundary wrapper).
psutil ships no py.typed (V2, 2026-07-11). This module is the ONE place core
touches the raw package; the vitals path reads system measurements through these
typed functions only. Local measurement only — no network (Invariant 2).
VirtualMemory
dataclass
The fields of psutil.virtual_memory() the vitals emitter reads.
total
instance-attribute
available
instance-attribute
percent
instance-attribute
virtual_memory()
process_rss(pid)
Resident-set size of pid, in bytes.
cpu_percent()
System-wide CPU percent since the previous call (non-blocking: interval=None).
loadavg_1m()
1-minute load average, or None on a platform without getloadavg.
sknetwork
Typed facade over sknetwork (type-system-as-core-audit.md §2.5 boundary wrapper).
scikit-network ships no py.typed (V2, 2026-07-11). This module is the ONE
place core touches the raw package — today that is the Louvain cross-check the
reasoning complex runs as a diagnostic beside its spectral partition. Offline
compute only — no network (Invariant 2).
The raw import stays lazy (inside the function): sknetwork is heavy and the
Louvain cross-check is off the live path, matching the call site's prior
behavior in core/complex/spectral.py.
louvain_labels(adjacency, *, resolution=1.0, random_state=0)
Modularity (Louvain) community labels for a (sparse) adjacency — one label per node.
Deterministic under the fixed random_state.