Skip to content

docs(skills): split graphstore-ingestion into -dsl + -builder#148

Merged
KailasMahavarkar merged 1 commit intomainfrom
docs/skill-caveman
Apr 19, 2026
Merged

docs(skills): split graphstore-ingestion into -dsl + -builder#148
KailasMahavarkar merged 1 commit intomainfrom
docs/skill-caveman

Conversation

@KailasMahavarkar
Copy link
Copy Markdown
Contributor

Previous `graphstore-ingestion` skill was 777 lines and mixed two very different audiences: LLMs emitting DSL text at runtime, and Python authors writing adapters with the typed builder. Each LLM session pays the full token cost of both.

Split

New skill Lines KB ~Tokens Audience
`graphstore-dsl` 425 19 5k LLM runtime. Emits DSL text for parser + execute.
`graphstore-builder` 674 27 7k Python adapter authors. Imports graphstore as a library.

Each drops content the other audience doesn't need. Combined they still cost less per-session than the old mega-skill, because only one loads per use case.

graphstore-dsl covers

  • Grammar reference (every verb + clause order)
  • WHERE / MATCH / BATCH syntax
  • String escape rules (`\"` inside literals)
  • Value types (str/num/NULL/NaN/time)
  • Reserved fields (`event_at`, `confidence`, etc.)
  • Gotchas G1-G12 (DSL-relevant subset)
  • Emission patterns: conversational ingest, belief extraction, query generation

graphstore-builder covers

  • Every `q.*` function with signature + DSL emission
  • `F` predicate algebra (eq, ne, gt, in_, contains, similar_score, etc.)
  • `P` pattern builder for MATCH
  • `agg` + `HavingExpr` comparisons
  • `Time` / `TimeExpr`
  • `EvolveWhen` / `EvolveThen`
  • Plugin registration (`register_verb`)
  • Composition (`|`, `.pipe`, `.with_`, `.limit`, `.where`)
  • Patterns A-F end-to-end in typed builder calls
  • Debug checklist

Verified against codebase

  • Every `q.` signature matches `src/graphstore/query/verbs/.py`
  • Config defaults match `src/graphstore/config.py`: `remember_weights=[0.52, 0.25, 0.15, 0.08]`, `recency_half_life_days=7300.0`, `graph_signal_enabled=True`, `fusion_method="weighted"`, `nucleus_expansion=False`
  • `P.node().to(P.var(), edge=F.eq(...))`, `q.sys.evolve.rule(when=[W.cond(...)], then=[A.run(...)])`, `q.aggregate_nodes(having=agg.count()>=10)` all dry-run through `.venv` and emit valid DSL

Other changes

  • `benchmarks/framework/adapters/graphstore_.py` docstring now points at `graphstore-builder` (adapter uses the Python API).

Em dash sweep

Zero em dashes in either new file (Rule 9).

Removed

`tools/skills/graphstore-ingestion/` - old skill removed.

…lder (python)

One-skill-fits-all was 777 lines and mixed two audiences. Split by the
actual consumer:

- tools/skills/graphstore-dsl/SKILL.md (425 lines, 19 KB, ~5k tokens)
  For runtime LLM emission of DSL text. Grammar reference, every verb
  with clause order, WHERE / MATCH / BATCH syntax, string escape rules,
  value types, gotchas. No Python API. Use when an LLM is ingesting,
  distilling, or querying at runtime and the output is text that gets
  parsed + executed line by line.

- tools/skills/graphstore-builder/SKILL.md (674 lines, 27 KB, ~7k tokens)
  For Python adapter authors importing graphstore. Full q/F/P/agg/Time/
  EvolveWhen/EvolveThen API with signatures + emission, composition
  primitives (.pipe, |, .with_), plugin registration, 6 patterns (A-F)
  rewritten end-to-end in typed builder calls. No DSL grammar dump.

Both reference each other for completeness. Descriptions spell out
which to load per use case.

Content verified against codebase:
- Every q.* signature matches src/graphstore/query/verbs/*.py
- Config defaults match src/graphstore/config.py (remember_weights
  [0.52, 0.25, 0.15, 0.08], recency_half_life_days 7300.0,
  graph_signal_enabled true, fusion_method weighted)
- P / F / agg / Time / EvolveWhen / EvolveThen APIs compile-checked
  via .venv/bin/python dry runs

benchmarks/framework/adapters/graphstore_.py docstring now points at
graphstore-builder (adapter uses the Python API, not runtime DSL).

Em dash sweep: zero in either new file (Rule 9).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@KailasMahavarkar KailasMahavarkar merged commit 6ab081f into main Apr 19, 2026
5 checks passed
@KailasMahavarkar KailasMahavarkar deleted the docs/skill-caveman branch April 19, 2026 20:35
KailasMahavarkar added a commit that referenced this pull request Apr 20, 2026
v0.4 ships retrieval observability triangle:
- REMEMBER signal telemetry + rich meta["signals"] (#150)
- SYS EXPLAIN REMEMBER dry-run (#151)
- ANSWER verb with pluggable reader LLM (#152)

Plus:
- Skills split: graphstore-dsl (runtime) + graphstore-builder (Python) (#148)
- Skill-guided LLM ingest adapter + LoCoMo wiring fix (#149)
- Docusaurus docs site @ graphstore-docs.orkait.com (#142-147)

Breaking changes: none. All additions are additive.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
KailasMahavarkar added a commit that referenced this pull request Apr 20, 2026
* chore(release): bump v0.3.0 -> v0.4.0

v0.4 ships retrieval observability triangle:
- REMEMBER signal telemetry + rich meta["signals"] (#150)
- SYS EXPLAIN REMEMBER dry-run (#151)
- ANSWER verb with pluggable reader LLM (#152)

Plus:
- Skills split: graphstore-dsl (runtime) + graphstore-builder (Python) (#148)
- Skill-guided LLM ingest adapter + LoCoMo wiring fix (#149)
- Docusaurus docs site @ graphstore-docs.orkait.com (#142-147)

Breaking changes: none. All additions are additive.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore(release): bump pyproject.toml version to 0.4.0

Missed in 07c9986. Pairs with src/graphstore/__init__.py bump.

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant