Skip to content

Library API: import graphier, plot the graph and chronology - #16

Merged
Joshuaakaspace merged 2 commits into
mainfrom
claude/semantica-repo-evaluation-essnux
Aug 16, 2026
Merged

Joshuaakaspace merged 2 commits into
mainfrom
claude/semantica-repo-evaluation-essnux

Conversation

@Joshuaakaspace

Copy link
Copy Markdown
Collaborator

Follows the merged #15. Graphier becomes a proper Python library, matplotlib-style — the knowledge graph and chronology in a script or Jupyter notebook, no web app required:

import graphier

v = graphier.open("~/notes")
v.entities("PERSON")                 # plain dicts, evidence included
v.relations("founded by")            # each edge carries its sentence
v.query("?- empire_builder(P, B)")   # Datalog over your own rules
v.conflicts(); v.timeline()
v.to_networkx()                      # hand the graph to any tool

v.plot_graph()                       # pip install graphier[viz]
v.plot_timeline()

What's in it

  • graphier.api.VaultSession — data access as plain dicts, every asserting row carrying its sentence evidence (same provenance discipline as the app and MCP server).
  • to_networkx() — the escape hatch: hand the typed graph (predicates, origins, evidence on edges) to pyvis, plotly, gephi, or your own analysis. UNKNOWN noise nodes excluded by default.
  • plot_graph() — Kamada-Kawai layout, entity-type colors matching the app palette, degree-based node sizing, predicate edge labels, type legend. DATE nodes excluded from the drawing by default (they connect to everything; the timeline plot covers time) — documented and overridable.
  • plot_timeline() — entity lifelines: rows per entity on a shared year axis, a dot per dated event, span lines, recessive grid.
  • matplotlib is optional (graphier[viz] extra); without it the plot methods raise a friendly one-line install hint (tested), keeping the base install lean.

Both README figures are real output from the demo vault:

plot_graph

plot_timeline

Testing

4 new tests (59 total): data access + Datalog + entity dossier through the public API, networkx export with edge evidence, both plots rendering with real artists and correct row labels under the Agg backend, and the friendly no-matplotlib error. CI now installs matplotlib so the plot tests run there too.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QVbxD1gd3gsC6zXKE6L3ya


Generated by Claude Code

claude added 2 commits August 16, 2026 07:50
matplotlib-style package use — same graph, same provenance, no web app:

    import graphier
    v = graphier.open('~/notes')
    v.entities('PERSON'); v.relations('founded by')
    v.query('?- empire_builder(P, B)')
    v.to_networkx()
    v.plot_graph(); v.plot_timeline()

- graphier.api.VaultSession: entities/relations/entity/search/query/
  conflicts/inferred/timeline as plain dicts, every asserting row
  carrying its sentence evidence; to_networkx() for interop with any
  graph tool (pyvis, plotly, gephi…).
- plot_graph(): kamada-kawai layout, entity-type colors matching the
  app palette, degree-based sizing, predicate edge labels, type legend.
  UNKNOWN and DATE nodes excluded from the drawing by default (data
  remains available); to_networkx() excludes only UNKNOWN.
- plot_timeline(): entity lifelines — rows per entity on a shared year
  axis, dots per dated event, span lines, recessive grid.
- matplotlib is optional via the graphier[viz] extra; without it the
  plot methods raise a friendly install hint (tested).
- README gains a 'Use it as a library' section with generated figures;
  CI installs matplotlib so plot tests run; CHANGELOG updated.
- 4 new tests (59 total).

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QVbxD1gd3gsC6zXKE6L3ya
plot_graph:
- Only typed relations are drawn by default; generic related_to
  co-occurrence edges are excluded from the drawing (include_related=True
  restores them) — they were the grey mesh drowning the signal.
- Curved edges with proper arrowheads; italic predicate labels on a soft
  ground chip; node labels sit below nodes with a paper-color halo and
  greedy collision nudging, never on top of the mark.
- Warm paper background matching the app, left-aligned bold title,
  frameless title-cased legend, comfortable margins.

plot_timeline:
- Year-span annotations at the end of each lifeline (1942–2024).
- Round-capped span lines, paper-ring dots, recessive grid, no spines,
  left-aligned bold title, x padding so annotations never clip.

Both README figures regenerated from the demo vault.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QVbxD1gd3gsC6zXKE6L3ya
@Joshuaakaspace
Joshuaakaspace merged commit ad5ed2e into main Aug 16, 2026
2 checks passed
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.

2 participants