Add kyu-api README and crate metadata

Author: darmie

crates/kyu-api/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.1.0"
 edition = "2024"
 description = "Database and Connection API for KyuGraph with Arrow Flight support"
 license = "MIT"
+readme = "README.md"
 repository = "https://github.com/offbit-ai/kyugraph"
 
 [dependencies]

crates/kyu-api/README.md

@@ -0,0 +1,150 @@
+# kyu-api
+
+Database and Connection API for [KyuGraph](https://crates.io/crates/kyu-graph) with Arrow Flight support.
+
+This crate is the internal engine API. Most users should depend on [`kyu-graph`](https://crates.io/crates/kyu-graph) instead, which re-exports the public surface from this crate.
+
+## Core Types
+
+| Type | Description |
+|------|-------------|
+| `Database` | Top-level entry point owning catalog, storage, WAL, and transaction manager |
+| `Connection` | Executes Cypher queries and DDL against a database |
+| `NodeGroupStorage` | Columnar storage backed by NodeGroup/ColumnChunk |
+
+## Usage
+
+```rust
+use kyu_api::{Database, Connection};
+
+// In-memory
+let db = Database::in_memory();
+let conn = db.connect();
+conn.query("CREATE NODE TABLE Person (id INT64, name STRING, PRIMARY KEY (id))").unwrap();
+conn.query("CREATE (p:Person {id: 1, name: 'Alice'})").unwrap();
+
+let result = conn.query("MATCH (p:Person) RETURN p.name").unwrap();
+for row in result.iter_rows() {
+    println!("{:?}", row);
+}
+```
+
+### Persistent Database
+
+```rust
+use kyu_api::Database;
+
+let db = Database::open(std::path::Path::new("./my_graph")).unwrap();
+let conn = db.connect();
+// Schema + data persisted to disk via WAL + checkpointing.
+```
+
+### Parameterized Queries
+
+```rust
+use std::collections::HashMap;
+use kyu_types::TypedValue;
+
+let mut params = HashMap::new();
+params.insert("min_age".to_string(), TypedValue::Int64(25));
+let result = conn.query_with_params(
+    "MATCH (p:Person) WHERE p.age > $min_age RETURN p.name",
+    params,
+).unwrap();
+```
+
+### Full VM Execution (params + env)
+
+```rust
+use std::collections::HashMap;
+use kyu_types::TypedValue;
+
+let params = HashMap::new();
+let env = HashMap::new();
+let result = conn.execute("MATCH (n) RETURN n", params, env).unwrap();
+```
+
+### Delta Fast Path
+
+Conflict-free idempotent upserts bypassing OCC for high-throughput ingestion:
+
+```rust
+use kyu_delta::{DeltaBatchBuilder, DeltaValue};
+
+let batch = DeltaBatchBuilder::new("source:my-pipeline", 1000)
+    .upsert_node("Person", "1", vec![], [("name", DeltaValue::String("Alice".into()))])
+    .build();
+let stats = conn.apply_delta(batch).unwrap();
+```
+
+### Extensions
+
+```rust
+use kyu_api::Database;
+use kyu_extension::Extension;
+
+let mut db = Database::in_memory();
+// db.register_extension(Box::new(my_ext));
+let conn = db.connect();
+```
+
+### Arrow Flight Server
+
+Expose KyuGraph as an Arrow Flight gRPC endpoint:
+
+```rust
+use std::sync::Arc;
+use kyu_api::{Database, serve_flight};
+
+let db = Arc::new(Database::in_memory());
+// serve_flight(db, "0.0.0.0", 50051).await.unwrap();
+```
+
+Convert query results to Arrow RecordBatch:
+
+```rust
+use kyu_api::to_record_batch;
+
+let result = conn.query("MATCH (p:Person) RETURN p.name, p.age").unwrap();
+if let Some(batch) = to_record_batch(&result) {
+    println!("Arrow schema: {:?}", batch.schema());
+}
+```
+
+## Architecture
+
+```
+Application
+    │
+    ▼
+┌─────────┐     ┌────────────┐
+│ Database │────▶│ Connection │  ← you are here (kyu-api)
+└─────────┘     └────────────┘
+    │                │
+    ▼                ▼
+┌────────┐    ┌──────────────┐
+│Catalog │    │ kyu-executor │
+└────────┘    └──────────────┘
+    │                │
+    ▼                ▼
+┌──────────────────────────┐
+│  kyu-storage (columnar)  │
+└──────────────────────────┘
+    │
+    ▼
+┌──────────────────────────┐
+│  kyu-transaction (WAL)   │
+└──────────────────────────┘
+```
+
+## Query Pipeline
+
+1. **Parse** — `kyu-parser` lexes and parses Cypher into an AST
+2. **Bind** — `kyu-binder` resolves names against the catalog
+3. **Plan** — `kyu-planner` builds and optimizes a logical plan
+4. **Execute** — `kyu-executor` runs the plan against storage
+5. **Commit** — `kyu-transaction` persists via WAL + checkpoint
+
+## License
+
+MIT