Metadata-Version: 2.4
Name: graphfakos
Version: 0.0.7
Summary: Reusable graph viewer and provider contract for agent memory, source graphs, and knowledge graph workbenches
Author: GraphFakos Contributors
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/openminion/graphfakos
Project-URL: Repository, https://github.com/openminion/graphfakos
Project-URL: Issues, https://github.com/openminion/graphfakos/issues
Project-URL: Documentation, https://github.com/openminion/graphfakos/tree/main/docs
Project-URL: Download, https://pypi.org/project/graphfakos/
Keywords: agent,knowledge-graph,graph-viewer,memory,source-graph,visualization
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: Typing :: Typed
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build<2,>=1; extra == "dev"
Requires-Dist: pre-commit<5,>=4; extra == "dev"
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: ruff<0.16,>=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="GraphFakos logo" width="128" />
</p>

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

<p align="center">
  <strong>Provider-neutral graph lens for local exploration, review, and package viewers.</strong>
</p>

<p align="center">
  <a href="https://github.com/openminion/graphfakos">GitHub</a>
  · <a href="https://pypi.org/project/graphfakos/">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/graphfakos/"><img alt="PyPI" src="https://img.shields.io/badge/pypi-v0.0.7-3775A9"></a>
  <a href="https://pypi.org/project/graphfakos/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/graphfakos?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>

GraphFakos `v0.0.7` is a semantic-alpha graph viewer package. It gives graph
providers one shared set of DTOs, adapter contracts, static rendering, local
preview tools, and interaction payloads without taking ownership of the graph
itself.

## Read This First

1. Read [At a Glance](#at-a-glance) to confirm that GraphFakos is a viewer, not
   a graph database or fact engine.
2. Follow [Install](#install) and [Quick Start](#quick-start) to open the local
   workbench.
3. Read [Provider Contract](#provider-contract) before adapting another graph.
4. Use the [package docs](docs/README.md) for live sessions, interchange,
   accessibility, and UI contracts.
5. Read [Development](#development) before changing the package.

## Trust and Brand Safety

- Official GitHub: <https://github.com/openminion/graphfakos>
- Official website: <https://www.openminion.com>
- Official X account: <https://x.com/OpenMinion>

GraphFakos 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 | `graphfakos` |
| Current line | `v0.0.7` semantic alpha |
| Python | 3.11+ |
| Best fit | Shared local graph viewing across independent providers |
| Core contract | `GraphFakosProvider` |
| Main outputs | Static HTML, embeddable fragments, local preview, and portable artifacts |
| Not the claim | Graph truth, persistence, indexing, memory, or fact extraction |

## Common Commands

```bash
python3.11 -m pip install graphfakos
graphfakos-smoke
graphfakos-ui --serve --open
```

For a static artifact:

```bash
graphfakos-ui --html-out graph.html
```

## Install

Install from PyPI:

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

For a source checkout:

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

## Quick Start

Open the packaged demo workbench:

```bash
graphfakos-ui --serve --open
```

Render a provider-neutral graph from Python:

```python
from graphfakos import (
    GraphFakosGraph,
    GraphFakosNode,
    GraphFakosProvider,
    GraphFakosRequest,
    render_static_html,
)


class DemoProvider(GraphFakosProvider):
    provider_id = "demo"
    provider_label = "Demo Provider"
    graph_role = "example"
    capabilities = ("search",)

    def load_graph(self, request: GraphFakosRequest) -> GraphFakosGraph:
        return GraphFakosGraph(
            graph_id="demo",
            label="Demo Graph",
            provider_id=self.provider_id,
            provider_label=self.provider_label,
            graph_role=self.graph_role,
            capabilities=self.capabilities,
            nodes=(
                GraphFakosNode(
                    id="node:1",
                    label="First node",
                    kind="example",
                    summary="Provider-owned graph content.",
                ),
            ),
            edges=(),
        )


html = render_static_html(DemoProvider(), GraphFakosRequest(screen="explore"))
open("graph.html", "w", encoding="utf-8").write(html)
```

For a complete host adapter with actions and knowledge capture, run:

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

## What GraphFakos Provides

- provider-neutral node, edge, citation, provenance, request, and graph DTOs
- a typed provider protocol and reusable provider assertions
- explore, neighborhood, path, provenance, timeline, diff, status, and context
  views
- static HTML, embeddable fragments, JSON, Markdown, DOT, and replay artifacts
- local preview serving and same-origin interaction endpoints
- search, filters, saved views, perspectives, diagnostics, and camera state
- typed capture, graph-action, expansion, live-patch, and replay contracts
- a framework-neutral browser custom element and packaged viewer assets
- fixtures and helpers for adapter, accessibility, and browser validation

## What GraphFakos Does Not Provide

- durable graph or memory persistence
- source ingestion, parsing, or fact extraction
- truth, trust, freshness, lifecycle, or ranking semantics
- OpenMinion runtime policy or agent orchestration
- SophiaGraph memory behavior
- PragmaGraph indexing behavior
- a hosted multi-user graph service

GraphFakos displays explicit provider data. Providers decide what nodes and
edges mean, where data is stored, which actions are valid, and whether a write
is accepted.

## Provider Contract

A provider owns graph truth and implements `GraphFakosProvider`:

```python
from graphfakos import GraphFakosGraph, GraphFakosProvider, GraphFakosRequest


class MyProvider(GraphFakosProvider):
    provider_id = "my-provider"
    provider_label = "My Provider"
    graph_role = "third-party"
    capabilities = ("search", "neighborhood", "path")

    def load_graph(self, request: GraphFakosRequest) -> GraphFakosGraph: ...
```

Optional protocols add bounded expansion, knowledge capture, graph actions,
live updates, or provider-specific inspector fields. Keep persistence and
semantic decisions in the provider rather than hiding them in viewer code.

## How It Fits

| Package | Responsibility |
| --- | --- |
| SophiaGraph | Durable memory semantics and memory graph projections |
| PragmaGraph | Observed-fact semantics and source graph projections |
| OpenMinion | Runtime and operator-facing graph integration |
| GraphFakos | Shared viewer, interaction DTOs, and local rendering |

Package-specific `sophiagraph-ui` and `pragmagraph-ui` commands should remain
thin adapters: they map package-owned data into GraphFakos DTOs and delegate
the viewer behavior to GraphFakos.

## Development

```bash
make dev-install
make hooks-install
make check
```

Run `make browser-test` when changing browser behavior and `make release-check`
before publishing or changing the documented public surface.

## Docs and Release

- [`docs/README.md`](docs/README.md): package documentation map
- [`docs/ui-contracts.md`](docs/ui-contracts.md): viewer and interaction
  contracts
- [`docs/live-sessions.md`](docs/live-sessions.md): patches, cursors, and replay
- [`docs/artifact-interchange.md`](docs/artifact-interchange.md): portable
  artifacts
- [`docs/custom-provider-example.md`](docs/custom-provider-example.md): adapter
  walkthrough
- [`docs/accessibility.md`](docs/accessibility.md): keyboard and accessibility
  behavior
- [`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 GraphFakos or OpenMinion project or imply affiliation or
endorsement.
