Metadata-Version: 2.4
Name: pragmagraph
Version: 0.0.9
Summary: Standalone observed-fact graph substrate for code and document structure
Author: PragmaGraph Contributors
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/OpenMinion/pragmagraph
Project-URL: Download, https://pypi.org/project/pragmagraph/
Keywords: agent,knowledge-graph,code-intelligence,documents,observed-facts
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: graphfakos<1,>=0.0.9
Provides-Extra: server
Provides-Extra: precise
Requires-Dist: tree-sitter<1,>=0.25; extra == "precise"
Requires-Dist: tree-sitter-language-pack<2,>=1.8; extra == "precise"
Provides-Extra: scip
Requires-Dist: protobuf<8,>=7.35; extra == "scip"
Provides-Extra: dev
Requires-Dist: build<2,>=1; extra == "dev"
Requires-Dist: pre-commit<5,>=4; extra == "dev"
Requires-Dist: protobuf<8,>=7.35; extra == "dev"
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: ruff<1,>=0.11; extra == "dev"
Requires-Dist: tree-sitter<1,>=0.25; extra == "dev"
Requires-Dist: tree-sitter-language-pack<2,>=1.8; extra == "dev"
Requires-Dist: twine<7,>=5; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://www.openminion.com/brand/openminion-logo.png" alt="PragmaGraph logo" width="128" />
</p>

<h1 align="center">PragmaGraph</h1>

<p align="center">
  <strong>Deterministic observed-fact graphs for code, docs, artifacts, and Git history.</strong>
</p>

<p align="center">
  <a href="https://github.com/OpenMinion/pragmagraph">GitHub</a>
  · <a href="https://pypi.org/project/pragmagraph/">PyPI</a>
  · <a href="https://www.openminion.com">Website</a>
  · <a href="docs/README.md">Docs</a>
  · <a href="https://x.com/OpenMinion">X</a>
</p>

<p align="center">
  <a href="https://pypi.org/project/pragmagraph/"><img alt="PyPI" src="https://img.shields.io/badge/pypi-v0.0.9-3775A9"></a>
  <a href="https://pypi.org/project/pragmagraph/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/pragmagraph?cacheSeconds=300"></a>
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-blue"></a>
  <img alt="Status" src="https://img.shields.io/badge/status-alpha-6B7280">
</p>

PragmaGraph `v0.0.9` is a standalone public 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](#at-a-glance) to confirm the observed-fact boundary.
2. Follow [Install](#install) and [Quick Start](#quick-start) to index and query
   one local project.
3. Read [How It Fits](#how-it-fits) before mixing observed facts with durable
   memory or a graph viewer.
4. Use the [Ten Minute Tour](docs/ten-minute-tour.md) for the complete
   workspace, viewer, store, certification, and refresh path.
5. Read [Development](#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

| | |
| --- | --- |
| Package | `pragmagraph` |
| Current line | `v0.0.9` public alpha |
| Python | 3.11+ |
| Best fit | Reproducible source, document, artifact, and Git facts |
| Primary artifact | Deterministic JSON graph snapshot |
| Main surfaces | Index, query, refresh, report, export, workspace, service, and viewer adapter |
| Not the claim | Semantic inference, durable agent memory, or hosted graph infrastructure |

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

```bash
python3.11 -m pip install pragmagraph
pragmagraph-smoke --json
pragmagraph quickstart . --serve --open --json
pragmagraph investigate --config .pragmagraph/workspace.toml "RuntimeGraph" --json
pragmagraph freshness --config .pragmagraph/workspace.toml --json
```

## Install

Install the base package:

```bash
python3.11 -m pip install pragmagraph
```

Optional precise parser and native SCIP support:

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

For a source checkout:

```bash
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

Start with the one-command local loop:

```bash
pragmagraph quickstart . --serve --open --json
```

`quickstart` writes `.pragmagraph/workspace.toml` when it does not already
exist, refreshes the local snapshot, materializes the local store, and opens a
visual investigation panel through GraphFakos.

When you want the lower-level steps explicitly, run the same pieces yourself.

Index a local project:

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

Query the snapshot:

```bash
pragmagraph query .pragmagraph/snapshot.json "RuntimeGraph" --json
pragmagraph investigate .pragmagraph/snapshot.json "RuntimeGraph" --json
pragmagraph investigate --config .pragmagraph/workspace.toml "RuntimeGraph" --json
```

Refresh it explicitly:

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

Run the self-contained package example:

```bash
python3.11 examples/quickstart_flow.py
```

For a reusable workspace and local visual graph, continue with
[`docs/ten-minute-tour.md`](docs/ten-minute-tour.md).

## Command Map

The quickstart above is the shortest useful path. The grouped commands below
are the advanced surfaces behind the same observed-fact workflow.

| Need | Recommended command | Notes |
| --- | --- | --- |
| First local run | `pragmagraph quickstart . --json` | Creates config, workspace, store, and first visual artifact |
| Search facts | `pragmagraph investigate --config .pragmagraph/workspace.toml RuntimeGraph --json` | Compact structural bundle for one question |
| Open the visual view again | `pragmagraph demo-ui --config .pragmagraph/workspace.toml --serve --open --json` | Reuses the workspace config |
| Check freshness | `pragmagraph freshness --config .pragmagraph/workspace.toml --json` | Explicit status, no background watcher |
| Package or receive a graph | `graph-pack-export`, `graph-pack-verify`, `graph-pack-review` | Advanced portability surface |
| Serve repeated local queries | `serve`, `mcp-smoke`, `pragmagraph-server` | Advanced service/MCP surface |

Inspect, export, and benchmark a snapshot when you need lower-level artifacts:

```bash
pragmagraph report .pragmagraph/snapshot.json --json
pragmagraph export .pragmagraph/snapshot.json --format mermaid
pragmagraph graphify-export .pragmagraph/snapshot.json > graphify.json
pragmagraph graph-pack-verify .pragmagraph/graph-pack --json
pragmagraph graph-pack-review .pragmagraph/graph-pack \
  --snapshot-out .pragmagraph/imported-snapshot.json \
  --store-out .pragmagraph/imported.sqlite \
  --json
pragmagraph ui-preview \
  --screen graph_pack_review \
  --graph-pack .pragmagraph/graph-pack \
  --snapshot-out .pragmagraph/imported-snapshot.json \
  --store-out .pragmagraph/imported.sqlite \
  --json
pragmagraph benchmark .
```

`graph-pack-verify` is the receiver-side trust check for a portable pack: it
validates manifest counts, file checksums, optional store parity, and optional
evidence JSON before import.
`graph-pack-review` adds a receive-side summary and copyable import command
without mutating files.

Use `investigate` when you want a compact navigation bundle for one static
question. It returns matched nodes, structural match reasons, direct
neighborhood facts, path facts when two matches exist, freshness facts, and
copyable next commands. Presets include `file_map`, `symbol_map`, `doc_links`,
`changed_recently`, `orphans`, and `high_degree`; all remain lexical or
structural, with no LLM ranking or intent inference.

Open the same investigation as a local visual panel:

```bash
pragmagraph ui-preview \
  --screen investigation \
  --snapshot .pragmagraph/snapshot.json \
  --query RuntimeGraph \
  --preset symbol_map \
  --serve \
  --open
```

Follow observed Git provenance:

```bash
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:

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

Operate a workspace or materialized store:

```bash
pragmagraph workspace-init . \
  --workspace .pragmagraph/workspace --json
pragmagraph workspace-query .pragmagraph/workspace RuntimeGraph --json
pragmagraph store-search-explain \
  .pragmagraph/graph.sqlite RuntimeGraph --json
pragmagraph store-backends --probe-optional --json
pragmagraph certify .pragmagraph/snapshot.json --json
pragmagraph serve --snapshot .pragmagraph/snapshot.json
pragmagraph mcp-smoke --snapshot .pragmagraph/snapshot.json --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

| Package | Responsibility |
| --- | --- |
| OpenMinion | Agent runtime, turns, tools, sessions, and orchestration |
| SophiaGraph | Durable memory, provenance, lifecycle, and workspace knowledge |
| PragmaGraph | Deterministic observed facts from source and artifacts |
| GraphFakos | Provider-neutral graph viewing and interaction contracts |

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:

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

Open the visual graph:

```bash
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`](docs/viewer-contract.md) and
[`docs/storage-interchange.md`](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

```bash
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`](docs/README.md): package documentation map
- [`docs/ten-minute-tour.md`](docs/ten-minute-tour.md): shortest complete tour
- [`docs/standalone-product-cycle.md`](docs/standalone-product-cycle.md):
  end-to-end local product cycle
- [`docs/refresh-operations.md`](docs/refresh-operations.md): refresh and
  status contracts
- [`docs/service-mode.md`](docs/service-mode.md): local service boundary
- [`docs/workspace-mode.md`](docs/workspace-mode.md): persistent workspace
  contract
- [`docs/source-tree-owner-map.md`](docs/source-tree-owner-map.md): code owners
  and package layout
- [`API_COMPATIBILITY.md`](API_COMPATIBILITY.md): supported import roots
- [`RELEASING.md`](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.
