feat(tool): cg CLI + embedded opt-in feature flag (v0.6.6-dev) by genezhang · Pull Request #267 · genezhang/clickgraph

genezhang · 2026-04-03T19:25:22Z

Summary

New clickgraph-tool crate (cg binary): agent/script CLI for Cypher translation and execution without a running ClickGraph server
- cg sql — Cypher→SQL translation
- cg validate — parse + plan check
- cg query — execute via remote ClickHouse (Database::new_remote)
- cg nl — NL→Cypher via LLM (Anthropic default; any OpenAI-compatible API)
- cg schema show/validate/discover/diff — schema inspection and LLM-assisted discovery (no server hop needed)
- Config: ~/.config/cg/config.toml + CG_* env vars
clickgraph-embedded: embedded feature now opt-in — chdb not compiled by default. New Database::new_remote(schema, RemoteConfig) executes Cypher against external ClickHouse with no chdb dependency. sql_only() / query_to_sql() always available. clickgraph-ffi explicitly enables embedded.
Bug fix: removed leftover println!("DEBUG TryFrom RenderExpr: ...") in render_plan/render_expr.rs
Version: v0.6.5-dev → v0.6.6-dev; TCK count (383/402, 95.3%) added to README test coverage
Docs: README, CHANGELOG, STATUS, ROADMAP, CLAUDE.md, DEV_QUICK_START, copilot-instructions, AGENTS.md files, and wiki (Quick-Start-Guide, Embedded-Mode, Schema-Discovery, AI-Assistant-Integration-MCP, Home)

Test plan

cargo build -p clickgraph-tool builds successfully
cargo build -p clickgraph-embedded builds without chdb (no embedded feature)
cargo build -p clickgraph-ffi --features embedded builds with chdb
cg --schema <yaml> sql "MATCH (n:User) RETURN n.name" prints SQL
cg --schema <yaml> validate "MATCH (n:User) RETURN n" succeeds
cg --schema <yaml> schema show prints compact schema
cg --schema <yaml> schema validate succeeds
cargo test — all unit tests still pass

🤖 Generated with Claude Code

- New `clickgraph-tool` workspace crate (`cg` binary): agent/script CLI for Cypher translation and execution without a running server. Commands: sql, validate, query, nl (NL→Cypher via LLM), schema show/validate/discover/diff. Supports Anthropic (default) and any OpenAI-compatible API. Config via ~/.config/cg/config.toml. - `clickgraph-embedded`: make `embedded` feature (chdb) opt-in. Added `Database::new_remote(schema, RemoteConfig)` — executes Cypher against external ClickHouse with no chdb dependency. `sql_only()` and `query_to_sql()` always available. `clickgraph-ffi` now explicitly enables the `embedded` feature. - Remove leftover debug println in render_plan/render_expr.rs. - Version bump to v0.6.6-dev; TCK test count (383/402) added to README. - Docs: README, CHANGELOG, STATUS, ROADMAP, CLAUDE.md, DEV_QUICK_START, copilot-instructions, all AGENTS.md files updated. Wiki: Quick-Start-Guide (pre-built binaries), Embedded-Mode (3 constructors), Schema-Discovery (cg server-free path), AI-Assistant-Integration-MCP (cg agent path), Home (v0.6.6-dev). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Two framework-agnostic agent skills backed by the cg CLI: - skills/cypher.md — /cypher <NL query>: NL→Cypher→SQL→execute - skills/graph-schema.md — /graph-schema: show schema + validate skills/README.md covers installation for Claude Code, LangChain, AutoGen, CrewAI, and OpenAI function calling. Also: .gitignore negation for skills/, README and wiki updates. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…ration Wraps `cg schema discover` as a publishable agent skill: - Collects ClickHouse credentials from env/config/user input - Runs cg schema discover → show → validate - Guides user to set CG_SCHEMA and use /cypher next Also: skills/README.md and wiki (Agent-Skills, Schema-Discovery) updated to include the new skill and the three-path discovery comparison table. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…features - Separate v0.6.6-dev and v0.6.5-dev What's New sections - Add TCK (383/402, 95.3%) to v0.6.5-dev What's New; clarify 19 skipped = write operations (CREATE/SET/DELETE/MERGE) unsupported by design - Add agent skills to v0.6.6-dev What's New - Features section: add remote mode, TCK, GraphRAG write API, hybrid mode, new Agentic & AI Integration subsection (cg CLI, agent skills, MCP, DataFrame) - Update schema discovery entry to mention cg schema discover (no server needed) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- TCK (383/402, 95.3%) moved from v0.6.5-dev to v0.6.6-dev in both README What's New and CHANGELOG - 19 skipped TCK scenarios: clarified as Cypher write *syntax* not yet implemented, distinct from the programmatic write API already available in embedded mode; Cypher write support noted as planned - Known Limitations updated: "Cypher write syntax" replaces "Read-Only Engine" to accurately reflect that writes are available programmatically - Agent skills added to CHANGELOG 0.6.6-dev entry Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

genezhang

Code Review — CLI + embedded opt-in feature flag

The architecture and feature design are solid. The embedded feature flag refactor is clean and well-gated. The cg CLI fills a real gap for agent/script use without a running server.

Posting inline comments for the specific issues I found. Summary by priority:

Priority	Issue
Must fix	Wrong flag names in Schema-Discovery.md (`--ch-user` → `--user`)
Must fix	Wrong `RemoteConfig` field types in Embedded-Mode.md code example
Should fix	`ch_user == "default"` override logic conflates explicit vs unset
Should fix	`value_str`/`value_to_json` Debug fallback for Date/Timestamp/UUID/List
Nice to have	Add unit tests for `config.rs`, `schema_fmt.rs`, `extract_code_block`
Nice to have	Fix Python skill example; consider deduplicating `merge_batch_yaml`

Must-fix bugs: - docs: cg schema discover uses --user/--password not --ch-user/--ch-password (Schema-Discovery.md, skills/schema-discover.md) - docs: RemoteConfig fields user/password are String not Option<String>; add missing cluster_name field (Embedded-Mode.md) - config: fix sentinel bug — ch_user/ch_password are now Option<String> in Cli, using proper priority chain (explicit > config file > default) instead of comparing against literal "default" / "" (main.rs, config.rs) - query: add explicit Value::Date/Timestamp/UUID/List/Map arms to value_str and value_to_json; previously fell back to Rust Debug format - skills/README.md: fix Python example — execution branch now uses cg nl --execute instead of passing raw NL string to cg query - schema_discovery: move merge_batch_yaml/extract_yaml_list_items to clickgraph core crate (src/graph_catalog/schema_discovery.rs); remove duplicate from clickgraph-tool/src/commands/schema.rs Nit: - llm.rs: remove .or_else(|| None) no-op Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

genezhang and others added 6 commits April 3, 2026 12:25

code fmt and schema discovery doc

c10242e