Metadata-Version: 2.4
Name: pragmagraph
Version: 0.0.2
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
Provides-Extra: dev
Requires-Dist: build<2,>=1; extra == "dev"
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: ruff<1,>=0.11; 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="OpenMinion logo" width="128" />
</p>

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

<p align="center">
  <strong>Standalone observed-fact graph substrate for code and document structure.</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="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/pypi/v/pragmagraph?color=3775A9"></a>
  <a href="https://pypi.org/project/pragmagraph/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/pragmagraph"></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-published%20alpha-5B8DEF">
</p>

`pragmagraph` is a standalone observed-fact graph substrate for code and
document structure. The name comes from Greek `pragma` (`πρᾶγμα`), meaning a
deed, matter, fact, or thing done; in this package it frames the third brain as
a graph of reproducible structure: files, symbols, document sections, artifacts,
references, commits, and other facts an indexer can recover from source.

This `0.0.1` semantic alpha provides a small local source-graph MVP:
deterministic DTOs, JSON snapshots, a local code/document indexer, lexical and
structural query helpers, CLI commands, and fixture handoff artifacts for
future OpenMinion adapter work.

## Boundary

- **Sophiagraph** owns inferred, judged, lossy durable memory.
- **PragmaGraph** owns observed, indexer-extracted, reproducible facts and
  deeds.
- **Graphify** remains the first third-brain adapter. PragmaGraph is the future
  native package, not a relabeling of Graphify.

Practical rule: if a parser, static analyzer, doc walker, git reader, or shell
command can reproduce the fact without an LLM, it belongs in PragmaGraph. If it
depends on a preference, operator pin, summary, design judgment, or memory
consolidation decision, it belongs in Sophiagraph. Sophiagraph may cite
PragmaGraph with `pragma://...` evidence references; PragmaGraph never stores
Sophiagraph's judgments.

## Trust and Brand Safety

- Official GitHub: `https://github.com/openminion/pragmagraph`
- Official PyPI: `https://pypi.org/project/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.

## License and brand-use boundary

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

The software license grants rights to use, modify, and redistribute the code.
It does **not** grant rights to use the PragmaGraph, Sophiagraph, or OpenMinion
names, logos, branding, website identity, or social identity except for
truthful attribution. Forks, clones, and derivative distributions must not
present themselves as the official PragmaGraph project or imply affiliation,
endorsement, or maintenance by PragmaGraph or OpenMinion contributors unless
that is actually true.

## What the package provides

The package currently provides:

- package metadata and Apache-2.0 release files
- stable alpha import roots:
  - `pragmagraph`
  - `pragmagraph.contracts`
  - `pragmagraph.models`
  - `pragmagraph.query`
  - `pragmagraph.storage`
  - `pragmagraph.adapters`
  - `pragmagraph.portability`
- immutable DTOs for source refs, graph nodes, graph edges, snapshots, query
  hits, omitted diagnostics, path results, and health summaries
- deterministic JSON snapshot load/save helpers
- a local indexer for directories, files, Markdown headings, Python AST
  definitions/imports, and lexical snippets
- query, neighborhood, path, and health helpers over loaded snapshots
- CLI commands for `index`, `query`, `neighborhood`, `path`, and `health`
- a semantic smoke entrypoint for install validation
- package-local tests, lint, and release-check workflow
- API compatibility and release docs

## What the package does not provide yet

This package does **not** currently provide:

- SQLite, KuzuDB, Neo4j, hosted, vector, or typed-edge storage
- Graphify runtime API wrapping or Graphify replacement behavior
- file watchers, git hooks, daemons, or scheduled refresh
- OpenMinion runtime provider wiring
- prompt context merging
- semantic inference from prose or model output
- automatic Sophiagraph memory writes or promotion

Those features belong to follow-on releases or to OpenMinion's provider
adapter layer.

## Install

Install from PyPI:

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

Editable install during local development:

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

Install with development tools:

```bash
python3.11 -m pip install -e ".[dev]"
```

Wheel build:

```bash
python3.11 -m build
```

## Standalone Smoke

Source-root smoke:

```bash
PYTHONPATH=src python3.11 -m pragmagraph --json
```

Installed-console-script smoke:

```bash
pragmagraph-smoke --json
```

Expected output is deterministic JSON with the package name, version, status,
stable import roots, and `semantic_contract: true`.

## CLI Quickstart

Index a local code/docs root into a deterministic JSON snapshot:

```bash
pragmagraph index . --out .pragmagraph/snapshot.json --namespace my-project --json
```

Query the snapshot:

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

Inspect nearby graph facts:

```bash
pragmagraph neighborhood .pragmagraph/snapshot.json \
  "pragma://my-project/file/src/app.py" --json
```

Check health:

```bash
pragmagraph health .pragmagraph/snapshot.json --json
```

## External Consumer Quickstart

Minimal standalone flow for another framework or service:

```python
import pragmagraph

snapshot = pragmagraph.index_path(".", namespace="example")
pragmagraph.save_snapshot(snapshot, ".pragmagraph/snapshot.json")
print(pragmagraph.PACKAGE_STATUS)
```

The package can also be checked from a shell:

```bash
python3.11 -m pragmagraph --json
```

See [API_COMPATIBILITY.md](API_COMPATIBILITY.md) for the public import-root
policy and [RELEASING.md](RELEASING.md) for package-local release checks.
