PragmaGraph

Deterministic observed-fact graphs for code, docs, artifacts, and Git history.

GitHub · PyPI · Website · Docs · X

PragmaGraph v0.0.7 is a standalone semantic-alpha package for facts that can be reproduced from source. It indexes local code, documents, artifacts, and Git history into deterministic graph snapshots without asking an LLM to decide what is true.

Read This First

1. Read At a Glance to confirm the observed-fact boundary.
2. Follow Install and Quick Start to index and query one local project.
3. Read How It Fits before mixing observed facts with durable memory or a graph viewer.
4. Use the Ten Minute Tour for the complete workspace, viewer, store, certification, and refresh path.
5. Read Development before changing the package.

Trust and Brand Safety

• Official GitHub: https://github.com/openminion/pragmagraph
• Official website: https://www.openminion.com
• Official X account: https://x.com/OpenMinion

PragmaGraph has no official token, coin, NFT, airdrop, staking program, treasury product, or investment offering. Any claim otherwise is unauthorized and should be treated as a scam.

At a Glance

Practical rule: if a parser, static analyzer, document walker, Git reader, or explicit command can reproduce a fact without an LLM, it belongs in PragmaGraph.

Common Commands

python3.11 -m pip install pragmagraph
pragmagraph-smoke --json
pragmagraph index . --out .pragmagraph/snapshot.json --namespace demo --json
pragmagraph query .pragmagraph/snapshot.json "RuntimeGraph" --json
pragmagraph-ui --serve --open --json

Install

Install the base package:

python3.11 -m pip install pragmagraph

Optional precise parser and native SCIP support:

python3.11 -m pip install "pragmagraph[precise]"
python3.11 -m pip install "pragmagraph[scip]"

For a source checkout:

python3.11 -m pip install -e ".[dev]"
python3.11 -m pip install -e ".[precise]"
python3.11 -m pip install -e ".[scip]"

Quick Start

External Consumer Quickstart

Index a local project:

pragmagraph index . \
  --out .pragmagraph/snapshot.json \
  --namespace demo \
  --git-identity-mode name_email_hash \
  --json

Query the snapshot:

pragmagraph query .pragmagraph/snapshot.json "RuntimeGraph" --json

Refresh it explicitly:

pragmagraph refresh . \
  --out .pragmagraph/snapshot.json \
  --manifest-out .pragmagraph/manifest.json \
  --namespace demo \
  --json

Run the package example:

python3.11 examples/basic_usage.py

For a reusable workspace and local visual graph, continue with docs/ten-minute-tour.md.

Command Map

The quickstart above is the shortest useful path. These grouped commands make the broader public surface easier to discover without requiring a full CLI reference read.

Inspect, export, and benchmark a snapshot:

pragmagraph report .pragmagraph/snapshot.json --json
pragmagraph export .pragmagraph/snapshot.json --format mermaid
pragmagraph graphify-export .pragmagraph/snapshot.json > graphify.json
pragmagraph benchmark .

Follow observed Git provenance:

pragmagraph git-commits-for-path .pragmagraph/snapshot.json src/app.py --json
pragmagraph git-files-for-commit .pragmagraph/snapshot.json abc123def456 --json
pragmagraph git-commits-for-symbol \
  .pragmagraph/snapshot.json RuntimeGraph --json

Import precise SCIP facts explicitly:

pragmagraph precise-import index.scip \
  --root . --namespace demo --out precise-snapshot.json --json

Operate a workspace or materialized store:

pragmagraph workspace-init . \
  --workspace .pragmagraph/workspace --json
pragmagraph workspace-query .pragmagraph/workspace RuntimeGraph --json
pragmagraph store-search-explain \
  .pragmagraph/graph.sqlite RuntimeGraph --json
pragmagraph certify .pragmagraph/snapshot.json --json
pragmagraph serve --snapshot .pragmagraph/snapshot.json

What PragmaGraph Provides

• immutable graph DTOs for nodes, edges, source references, queries, and snapshots
• deterministic indexing for code, Markdown, selected configuration, schemas, manifests, CI workflows, and Git history
• explicit refresh manifests, structural deltas, and CI comparisons
• neighborhood, path, reverse-edge, impact, explanation, and query-plan helpers
• JSON and SQLite-backed storage interchange
• reports plus JSON, Markdown, DOT, Mermaid, Graphify, and SCIP-oriented interchange
• multi-root composition and exact cross-repository symbol resolution
• workspace, local service, read-only MCP, benchmark, certification, and privacy surfaces
• a provider adapter for GraphFakos and package-owned visual preview commands

What PragmaGraph Does Not Provide

• LLM-based fact extraction or semantic judgment
• durable agent memory, memory promotion, or preference storage
• implicit background watchers, Git hooks, cron jobs, or daemons
• hosted HTTP, WebSocket, indexing, or collaboration infrastructure
• OpenMinion orchestration or prompt-context merging
• ownership of GraphFakos viewer behavior
• automatic execution of external indexers

Refresh, ingestion, and precise-fact import are explicit. The package does not silently install tools, start background workers, or perform network discovery.

How It Fits

SophiaGraph may cite a PragmaGraph fact as evidence. PragmaGraph does not store SophiaGraph’s summaries, preferences, judgments, or memory decisions. GraphFakos may render a PragmaGraph projection but does not become the owner of the source facts.

Workspaces, Interchange, and Viewing

Create a reusable workspace configuration:

pragmagraph workspace-config-init . \
  --out .pragmagraph/workspace.toml \
  --workspace .pragmagraph/workspace \
  --label demo \
  --namespace demo \
  --ui-screen project_health \
  --json

Open the visual graph:

pragmagraph demo-ui \
  --config .pragmagraph/workspace.toml \
  --serve --open --json

PragmaGraph owns observed-fact semantics and the adapter payload. GraphFakos owns the reusable viewer shell. See docs/viewer-contract.md and docs/storage-interchange.md before integrating either boundary.

Stable consumer owners are exposed under pragmagraph.workspace and pragmagraph.ui; use those package surfaces rather than reaching into CLI implementation modules.

Development

make dev-install
make hooks-install
make check

Use make release-check before publishing or changing the documented public surface.

Docs and Release

• docs/README.md: package documentation map
• docs/ten-minute-tour.md: shortest complete tour
• docs/standalone-product-cycle.md: end-to-end local product cycle
• docs/refresh-operations.md: refresh and status contracts
• docs/service-mode.md: local service boundary
• docs/workspace-mode.md: persistent workspace contract
• docs/source-tree-owner-map.md: code owners and package layout
• API_COMPATIBILITY.md: supported import roots
• RELEASING.md: release and publish flow

License and Brand-use Boundary

• Source code license: Apache-2.0
• Brand/trademark grant: none

The license grants rights to use, modify, and redistribute the code. It does not grant rights to present a fork, clone, token, website, or social account as the official PragmaGraph or OpenMinion project or imply affiliation or endorsement.