# Python Parity Matrix (TypeScript Core)
Scope: TypeScript core API under `src/api/*` plus `src/api/vector-search.ts`, `Kite.check()` in `src/api/kite.ts`, and the operational helpers exported from `src/index.ts` (export/import, streaming, backup/restore, metrics/health). CLI helpers are excluded.
Legend: parity = full feature match, partial = similar capability with API or behavior differences, missing = not exposed in Python bindings.
## Fluent API
| Area | TypeScript (core) | Python | Parity | Notes |
| ----------------- | --------------------------------------------------- | -------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------- |
| Open/close | `kite(path, options)` / `Kite.open()` / `Kite.close()` | `kite(path, nodes, edges)` / `Kite(...)` / `close()` | parity | Python is sync; TS is async. |
| Schema | `node`, `edge`, `prop`, `optional` | `node`, `edge`, `prop`, `optional` | parity | Full parity. `defineNode`/`defineEdge` and `define_node`/`define_edge` kept as deprecated aliases. |
| Insert (single) | `insert(node).values({...}).returning()` | `insert(node).values(...).returning()` | parity | Python accepts dict or kwargs. |
| Insert (batch) | `insert(node).values([...]).returning()` | `insert(node).values([...]).returning()` | parity | Python list insert uses batch path. |
| Update (where) | `update(node).set(...).where({id/key})` | `update(node).set(...).where(id=..., key=...)` | parity | API shape differs. |
| Update by ref | `update(nodeRef).set(...).execute()` | `update(node_ref).set(...).execute()` | parity | Naming differences only. |
| Delete (where) | `delete(node).where({id/key})` | `delete(node).where(id=..., key=...)` | parity | API shape differs. |
| Delete by ref | `delete(nodeRef)` | `delete(node_ref)` | parity | Both execute immediately. |
| Get node | `get(node, key)` | `get(node, key)` | parity | Python returns props; TS returns props. |
| Get ref | `getRef(node, key)` | `get_ref(node, key)` | parity | Both skip prop loading. |
| Edge link/unlink | `link`, `unlink` | `link`, `unlink` | parity | Python accepts dict + kwargs for props. |
| Has edge | `hasEdge` | `has_edge` | parity | Naming difference only. |
| Update edge props | `updateEdge(...).set(...)` | `update_edge(...).set(...)` | parity | Naming difference only. |
| List nodes | `all(nodeDef)` async generator | `all(node_def)` iterator | partial | Sync vs async iteration. |
| Count nodes/edges | `count`, `countEdges` | `count`, `count_edges` | parity | Naming difference only. |
| List edges | `allEdges(edgeDef?)` async generator | `all_edges(edge_def?)` iterator | partial | Sync vs async iteration. |
## Traversal
| Area | TypeScript (core) | Python | Parity | Notes |
| ------------------------ | -------------------------------------- | ------------------------------------------- | ------- | ---------------------------------------------- |
| Steps | `out`, `in`, `both`, `traverse` | `out`, `in_`, `both`, `traverse` | parity | Python allows edge to be optional. |
| Select props | `select([...])` | `select([...])` | parity | Python also has `load_props` / `with_props`. |
| Filters | `whereEdge`, `whereNode` | `where_edge`, `where_node` | parity | Applied after traversal in both. |
| Traverse options filters | `TraverseOptions.whereEdge/whereNode` | `TraverseOptions.where_edge/where_node` | parity | Filters applied during traversal. |
| Property loading default | loads all props | loads all props | parity | Default behavior aligned. |
| Results | async iterator + `toArray/first/count` | sync iterator + `to_list/first/count` | partial | Behavior equivalent, sync vs async. |
| Edge results | `{ src, dst, etype, ...props }` | `EdgeResult` with `src/dst/etype` access | parity | Naming differences only. |
| Raw edges | `rawEdges()` | `raw_edges()` | parity | Same constraints (no variable-depth). |
## Pathfinding
| Area | TypeScript (core) | Python | Parity | Notes |
| ---------------- | ------------------------------------- | ------------------------------------- | ------- | ----------------------------------- |
| Builder | `shortestPath(source)` | `shortest_path(source)` | parity | Naming difference only. |
| Edge restriction | `via(edge)` required | `via(edge)` required | parity | Behavior aligned. |
| Targets | `to`, `toAny` | `to`, `to_any` | parity | Naming difference only. |
| Algorithms | `dijkstra`, `aStar`, `allPaths` | `dijkstra`, `a_star`, `all_paths` | parity | Naming differences only. |
| Weights | `{ property }` or `{ fn }` | `weight("prop")` or `weight(fn)` | partial | Different API shape; same behavior. |
| Result shape | `{ path, edges, totalWeight, found }` | `{ path, edges, totalWeight, found }` | parity | Aliases provided. |
| Prop loading | always loads props | always loads props | parity | Default behavior aligned. |
## Transactions and Maintenance
| Area | TypeScript (core) | Python | Parity | Notes |
| -------------- | ---------------------------------- | ---------------------------------- | ------- | -------------------------------------------- |
| Transaction | `transaction(fn)` with context | `transaction()` context manager | partial | Different API style, similar behavior. |
| Batch ops | `batch([...])` with `_toBatchOp()` | `batch([...])` callables/executors | partial | Same capability, different interface. |
| Stats | `stats()` | `stats()` | parity | Returns stats struct. |
| Check | `check()` | `check()` | parity | Schema warnings included. |
| Optimize | `optimize()` | `optimize()` | parity | Same behavior. |
| Export/Import | `export*`, `import*` | `export*`, `import*` | parity | Python exposes JSON object and file helpers. |
| Streaming | `stream*`, `get*Page` | `stream*`, `get*Page` | parity | Same batching/pagination behavior. |
| Backup/Restore | `createBackup`, `restoreBackup` | `create_backup`, `restore_backup` | parity | Naming differences only. |
| Metrics/Health | `collectMetrics`, `collectReplicationMetricsPrometheus`, `collectReplicationMetricsOtelJson`, `pushReplicationMetricsOtelJson`, `collectReplicationSnapshotTransportJson`, `collectReplicationLogTransportJson`, `healthCheck` | `collect_metrics`, `collect_replication_metrics_prometheus`, `collect_replication_metrics_otel_json`, `push_replication_metrics_otel_json`, `collect_replication_snapshot_transport_json`, `collect_replication_log_transport_json`, `health_check` | parity | Naming differences only. |
## Vector Search
| Area | TypeScript (core) | Python | Parity | Notes |
| ---------------- | ---------------------------------- | ------------------------------------ | ------- | -------------------------------------------------------------- |
| High-level index | `VectorIndex`, `createVectorIndex` | `VectorIndex`, `create_vector_index` | partial | Python uses in-memory store with optional IVF; no persistence. |
| IVF index | `createIvfIndex`, `ivfSearch` | `IvfIndex` | partial | Similar capability, different API surface. |
| IVF-PQ index | `ivf*` + PQ config | `IvfPqIndex` | partial | Similar capability, different API surface. |
## Remaining Gaps
- None noted.