# 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.
