graphfakos 0.0.1__py3-none-any.whl

graphfakos/__init__.py

@@ -0,0 +1,75 @@
+"""Reusable graph lens for agent memory and source knowledge graphs."""
+
+from .adapters import FixtureGraphProvider, build_fixture_graph
+from .models import (
+    GraphFakosCitation,
+    GraphFakosDiagnostics,
+    GraphFakosEdge,
+    GraphFakosGraph,
+    GraphFakosNode,
+    GraphFakosProvenance,
+    GraphFakosRequest,
+    GraphFakosScreen,
+    GraphFakosVisual,
+)
+from .provider import (
+    GraphFakosProvider,
+    diagnose_graph,
+    load_provider_graph,
+    validate_graph,
+)
+from .server import (
+    LocalViewerHttpServer,
+    LocalViewerServerResult,
+    RenderPath,
+    make_local_viewer_server,
+    serve_local_viewer,
+)
+from .static import render_static_html, write_static_html
+from .ui import render_graph_viewer, render_provider_path, screen_manifest
+
+__version__ = "0.0.1"
+PACKAGE_STATUS = "semantic-alpha"
+STABLE_IMPORT_ROOTS = (
+    "graphfakos",
+    "graphfakos.adapters",
+    "graphfakos.contracts",
+    "graphfakos.models",
+    "graphfakos.provider",
+    "graphfakos.render",
+    "graphfakos.server",
+    "graphfakos.static",
+    "graphfakos.testing",
+    "graphfakos.ui",
+)
+
+__all__ = [
+    "PACKAGE_STATUS",
+    "STABLE_IMPORT_ROOTS",
+    "__version__",
+    "FixtureGraphProvider",
+    "GraphFakosCitation",
+    "GraphFakosDiagnostics",
+    "GraphFakosEdge",
+    "GraphFakosGraph",
+    "GraphFakosNode",
+    "GraphFakosProvider",
+    "GraphFakosProvenance",
+    "GraphFakosRequest",
+    "GraphFakosScreen",
+    "GraphFakosVisual",
+    "LocalViewerHttpServer",
+    "LocalViewerServerResult",
+    "RenderPath",
+    "build_fixture_graph",
+    "diagnose_graph",
+    "load_provider_graph",
+    "make_local_viewer_server",
+    "render_graph_viewer",
+    "render_provider_path",
+    "render_static_html",
+    "screen_manifest",
+    "serve_local_viewer",
+    "validate_graph",
+    "write_static_html",
+]

graphfakos/__main__.py

@@ -0,0 +1,17 @@
+"""GraphFakos module entrypoint."""
+
+from __future__ import annotations
+
+import sys
+
+from .cli import main, ui_preview_main
+
+
+def _dispatch(argv: list[str]) -> int:
+    if argv and argv[0] == "ui-preview":
+        return ui_preview_main(argv[1:])
+    return main(argv)
+
+
+if __name__ == "__main__":
+    raise SystemExit(_dispatch(sys.argv[1:]))

graphfakos/adapters/__init__.py

@@ -0,0 +1,8 @@
+"""GraphFakos adapter helpers."""
+
+from .fixture import FixtureGraphProvider, build_fixture_graph
+
+__all__ = [
+    "FixtureGraphProvider",
+    "build_fixture_graph",
+]

graphfakos/adapters/fixture.py

@@ -0,0 +1,166 @@
+"""Fake third-party provider used by tests and examples."""
+
+from __future__ import annotations
+
+from graphfakos.models import (
+    GraphFakosCitation,
+    GraphFakosEdge,
+    GraphFakosGraph,
+    GraphFakosNode,
+    GraphFakosProvenance,
+    GraphFakosRequest,
+)
+
+
+def build_fixture_graph(request: GraphFakosRequest | None = None) -> GraphFakosGraph:
+    request = request or GraphFakosRequest()
+    provenance = (
+        GraphFakosProvenance(
+            id="prov:fixture",
+            provider_id="fixture",
+            source_type="third_party",
+            source_label="Fixture provider",
+            excerpt="Synthetic graph for provider contract tests.",
+            observed_at="2026-06-22T00:00:00+00:00",
+            confidence=1.0,
+        ),
+    )
+    citations = (
+        GraphFakosCitation(
+            id="cite:fixture-readme",
+            label="Fixture README",
+            path="README.md",
+            line=1,
+            excerpt="Fixture graph source.",
+        ),
+    )
+    nodes = (
+        GraphFakosNode(
+            id="memory:operator-preference",
+            label="Operator Preference",
+            kind="memory",
+            summary="The operator prefers copyable local validation commands.",
+            tags=("preference", "memory"),
+            score=0.98,
+            source="fixture",
+            provenance_ids=("prov:fixture",),
+            citation_ids=("cite:fixture-readme",),
+        ),
+        GraphFakosNode(
+            id="document:viewer-spec",
+            label="Viewer Spec",
+            kind="document",
+            summary="Graph viewer requirements for package integration.",
+            tags=("document", "viewer"),
+            source="fixture",
+            provenance_ids=("prov:fixture",),
+        ),
+        GraphFakosNode(
+            id="artifact:static-export",
+            label="Static Export",
+            kind="artifact",
+            summary="Portable HTML export generated by GraphFakos.",
+            tags=("artifact", "html"),
+            source="fixture",
+        ),
+        GraphFakosNode(
+            id="provider:third-party",
+            label="Third-party Provider",
+            kind="provider",
+            summary="Provider implementing the GraphFakos protocol.",
+            tags=("provider", "third_party"),
+            source="fixture",
+        ),
+    )
+    edges = (
+        GraphFakosEdge(
+            id="edge:preference-supports-spec",
+            source_id="memory:operator-preference",
+            target_id="document:viewer-spec",
+            kind="supports",
+            label="supports",
+            confidence=0.9,
+            provenance_ids=("prov:fixture",),
+        ),
+        GraphFakosEdge(
+            id="edge:spec-produces-export",
+            source_id="document:viewer-spec",
+            target_id="artifact:static-export",
+            kind="produces",
+            label="produces",
+            confidence=0.85,
+        ),
+        GraphFakosEdge(
+            id="edge:provider-serves-spec",
+            source_id="provider:third-party",
+            target_id="document:viewer-spec",
+            kind="serves",
+            label="serves",
+            confidence=0.88,
+        ),
+        GraphFakosEdge(
+            id="edge:provider-serves-export",
+            source_id="provider:third-party",
+            target_id="artifact:static-export",
+            kind="serves",
+            label="serves",
+            confidence=0.82,
+        ),
+    )
+    return GraphFakosGraph(
+        graph_id="fixture",
+        label="Fixture Knowledge Graph",
+        provider_id="fixture",
+        provider_label="Fixture Provider",
+        graph_role="third_party",
+        capabilities=(
+            "search",
+            "neighborhood",
+            "path",
+            "provenance",
+            "provider_status",
+            "static_export",
+            "local_preview",
+        ),
+        nodes=nodes,
+        edges=edges,
+        provenance=provenance,
+        citations=citations,
+        warnings=(),
+        stats={"request_screen": request.screen, "node_count": len(nodes)},
+        generated_at="2026-06-22T00:00:00+00:00",
+        provider_payload={
+            "integration_summary": (
+                "This fixture shows how a package-local provider can publish "
+                "viewer-ready graph DTOs without importing any host runtime."
+            ),
+            "integration_commands": (
+                "graphfakos-ui --screen explore --html-out graphfakos-ui-preview.html --json",
+                "graphfakos-ui --screen provider_status --serve --open",
+            ),
+        },
+    )
+
+
+class FixtureGraphProvider:
+    provider_id = "fixture"
+    provider_label = "Fixture Provider"
+    graph_role = "third_party"
+    capabilities = (
+        "search",
+        "neighborhood",
+        "path",
+        "provenance",
+        "provider_status",
+        "static_export",
+        "local_preview",
+    )
+
+    def load_graph(self, request: GraphFakosRequest) -> GraphFakosGraph:
+        return build_fixture_graph(request)
+
+
+__all__ = [
+    "FixtureGraphProvider",
+    "build_fixture_graph",
+]

graphfakos/cli.py

@@ -0,0 +1,152 @@
+"""Command-line entrypoints for GraphFakos."""
+
+from __future__ import annotations
+
+import argparse
+import json
+
+from .adapters import FixtureGraphProvider
+from .models import GraphFakosRequest, GraphFakosScreen
+from .server import serve_local_viewer
+from .static import write_static_html
+from .ui import render_provider_path
+
+_SCREENS: tuple[GraphFakosScreen, ...] = (
+    "explore",
+    "neighborhood",
+    "path",
+    "provenance",
+    "timeline",
+    "provider_status",
+    "context_preview",
+)
+
+
+def smoke_payload() -> dict[str, object]:
+    return {
+        "package": "graphfakos",
+        "version": "0.0.1",
+        "status": "semantic-alpha",
+        "semantic_contract": True,
+        "openminion_imports": False,
+        "stable_import_roots": [
+            "graphfakos",
+            "graphfakos.adapters",
+            "graphfakos.contracts",
+            "graphfakos.models",
+            "graphfakos.provider",
+            "graphfakos.render",
+            "graphfakos.server",
+            "graphfakos.static",
+            "graphfakos.testing",
+            "graphfakos.ui",
+        ],
+    }
+
+
+def _request_from_args(args: argparse.Namespace) -> GraphFakosRequest:
+    filters = {
+        key: value
+        for key, value in {
+            "node_kind": args.node_kind,
+            "edge_kind": args.edge_kind,
+            "tag": args.tag,
+            "source": args.source,
+            "min_score": args.min_score,
+        }.items()
+        if value not in (None, "")
+    }
+    return GraphFakosRequest(
+        screen=args.screen,
+        query=args.query,
+        focus_node_id=args.focus_node_id,
+        selected_edge_id=args.selected_edge_id,
+        source_node_id=args.source_node_id,
+        target_node_id=args.target_node_id,
+        max_depth=args.max_depth,
+        filters=filters,
+        layout=args.layout,
+        limit=args.limit,
+    )
+
+
+def _print_payload(payload: object, *, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(payload, sort_keys=True))
+        return
+    print(payload)
+
+
+def ui_preview_main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="GraphFakos local graph viewer")
+    parser.add_argument("--screen", choices=_SCREENS, default="explore")
+    parser.add_argument("--query", default="")
+    parser.add_argument("--focus-node-id")
+    parser.add_argument("--selected-edge-id")
+    parser.add_argument("--source-node-id")
+    parser.add_argument("--target-node-id")
+    parser.add_argument("--max-depth", type=int, default=1)
+    parser.add_argument("--node-kind", default="")
+    parser.add_argument("--edge-kind", default="")
+    parser.add_argument("--tag", default="")
+    parser.add_argument("--source", default="")
+    parser.add_argument("--min-score", default="")
+    parser.add_argument("--layout", default="force")
+    parser.add_argument("--limit", type=int, default=25)
+    parser.add_argument("--html-out", default="graphfakos-ui-preview.html")
+    parser.add_argument("--serve", action="store_true")
+    parser.add_argument("--open", action="store_true")
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8767)
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+
+    provider = FixtureGraphProvider()
+    request = _request_from_args(args)
+    if args.serve:
+        result = serve_local_viewer(
+            render_path=lambda path, query: render_provider_path(
+                provider,
+                request,
+                path,
+                query,
+            ),
+            default_path=f"/{request.screen}",
+            host=args.host,
+            port=args.port,
+            open_browser=args.open,
+        )
+        _print_payload(result.to_dict(), as_json=args.json)
+        return 0
+
+    payload = write_static_html(
+        provider,
+        request,
+        args.html_out,
+        open_browser=args.open,
+    )
+    graph = provider.load_graph(request)
+    payload.update(
+        {
+            "provider_id": graph.provider_id,
+            "node_count": len(graph.nodes),
+            "edge_count": len(graph.edges),
+        }
+    )
+    _print_payload(payload, as_json=args.json)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="graphfakos package smoke")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+    _print_payload(smoke_payload(), as_json=args.json)
+    return 0
+
+
+__all__ = [
+    "main",
+    "smoke_payload",
+    "ui_preview_main",
+]

graphfakos/contracts.py

@@ -0,0 +1,35 @@
+"""Public provider contract exports for GraphFakos adapters."""
+
+from .models import (
+    GraphFakosCitation,
+    GraphFakosDiagnostics,
+    GraphFakosEdge,
+    GraphFakosGraph,
+    GraphFakosNode,
+    GraphFakosProvenance,
+    GraphFakosRequest,
+    GraphFakosScreen,
+    GraphFakosVisual,
+)
+from .provider import (
+    GraphFakosProvider,
+    diagnose_graph,
+    load_provider_graph,
+    validate_graph,
+)
+
+__all__ = [
+    "GraphFakosCitation",
+    "GraphFakosDiagnostics",
+    "GraphFakosEdge",
+    "GraphFakosGraph",
+    "GraphFakosNode",
+    "GraphFakosProvider",
+    "GraphFakosProvenance",
+    "GraphFakosRequest",
+    "GraphFakosScreen",
+    "GraphFakosVisual",
+    "diagnose_graph",
+    "load_provider_graph",
+    "validate_graph",
+]