Graphinate 0.15.3__tar.gz → 0.16.0__tar.gz

{graphinate-0.15.3 → graphinate-0.16.0}/CHANGELOG.md

@@ -1,3 +1,13 @@
+## v0.16.0 (2026-10-17)
+
+### Feat
+
+- **GEP-017**: Exposes `create_app` for Starlette application setup.
+
+### Fix
+
+- Adds model compilation and refines node and GraphQL builders.
+
 ## v0.15.3 (2026-10-17)
 
 ### Fix

{graphinate-0.15.3 → graphinate-0.16.0}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.5
 Name: Graphinate
-Version: 0.15.3
+Version: 0.16.0
 Summary: Graphinate. Data to Graphs.
 Project-URL: Homepage, https://erivlis.github.io/graphinate
 Project-URL: Documentation, https://erivlis.github.io/graphinate
 Project-URL: Bug Tracker, https://github.com/erivlis/graphinate/issues
 Project-URL: Source, https://github.com/erivlis/graphinate
 Author-email: Eran Rivlis <eran@rivlis.info>
+License-Expression: LGPL-3.0-or-later
 License-File: LICENSE
 Keywords: declarative,graph
 Classifier: Development Status :: 4 - Beta
@@ -208,7 +209,7 @@ or
 uv add graphinate[server] 
 ```
 
-**Graphinate** officially supports Python >= 3.10.
+**Graphinate** officially supports Python >= 3.11.
 
 ### Example
 
@@ -251,7 +252,7 @@ mermaid_markdown: str = graphinate.mermaid.markdown(diagram)
 mermaid_html: str = graphinate.mermaid.html(diagram, title=graph_model.name)
 
 # or use the GraphQL Builder
-builder = graphinate.builders.GraphQLBuilder(.graph_model)
+builder = graphinate.builders.GraphQLBuilder(graph_model)
 
 # to create a Strawberry GraphQL schema
 schema = builder.build()

{graphinate-0.15.3 → graphinate-0.16.0}/README.md

@@ -159,7 +159,7 @@ or
 uv add graphinate[server] 
 ```
 
-**Graphinate** officially supports Python >= 3.10.
+**Graphinate** officially supports Python >= 3.11.
 
 ### Example
 
@@ -202,7 +202,7 @@ mermaid_markdown: str = graphinate.mermaid.markdown(diagram)
 mermaid_html: str = graphinate.mermaid.html(diagram, title=graph_model.name)
 
 # or use the GraphQL Builder
-builder = graphinate.builders.GraphQLBuilder(.graph_model)
+builder = graphinate.builders.GraphQLBuilder(graph_model)
 
 # to create a Strawberry GraphQL schema
 schema = builder.build()

graphinate-0.16.0/design/proposals/GEP-003_Roadmap.md

@@ -0,0 +1,122 @@
+# GEP-003: Graphinate Development Roadmap
+
+| Field       | Value                   |
+|:------------|:------------------------|
+| **GEP**     | 3                       |
+| **Title**   | Development Roadmap     |
+| **Author**  | Eran Rivlis             |
+| **Status**  | Active                  |
+| **Type**    | Process                 |
+| **Created** | 2025-12-30              |
+| **Updated** | 2026-10-17              |
+
+## Abstract
+
+This document outlines the strategic execution plan for the Graphinate Enhancement Proposals (GEPs). It serves as a living document to track the prioritization and status of major initiatives.
+
+## Phase 1: Stabilization (Completed)
+
+*Focus: Fixing brittle code, security risks, and "bad magic". All Phase 1 stabilization proposals (**GEP-010**, **GEP-016**, **GEP-017**, **GEP-025**, **GEP-032**) have been implemented and archived.*
+
+## Phase 2: Core Spine & Architectural Health
+
+*Focus: Strengthening the core execution engine, schema generation, and modularity.*
+
+| GEP         | Title                                         | Impact   | Difficulty | Rationale                                                                                                                            |
+|:------------|:----------------------------------------------|:---------|:-----------|:-------------------------------------------------------------------------------------------------------------------------------------|
+| **GEP-024** | **The Graph Engine**                          | **High** | **Hard**   | **Core Architecture.** Extracting the execution logic is the foundation for Async, Realtime, and better testing. Supersedes GEP-015. |
+| **GEP-014** | **Explicit GraphQL Schema Generation**        | **High** | **Hard**   | **Major Refactor.** Refactoring dynamic class generation to `strawberry.tools.create_type` and context-injected resolvers.           |
+| **GEP-023** | **Async Support**                             | **High** | **Hard**   | **Performance.** Massive gains for I/O-bound crawling (`async def` generators). Dependent on GEP-024.                                |
+| **GEP-019** | **Offline Viewer Support**                    | Medium   | Easy       | **Reliability.** GraphiQL/Voyager are vendored; completing local vendoring for `viewer` removes remaining CDN dependencies.          |
+| **GEP-031** | **High-Performance Vectorized Operations**    | Medium   | Medium     | **Performance.** Progressive enhancement via optional NumPy/Numba (partially active in `color.py`).                                  |
+| **GEP-011** | **Standardized Element Factory**              | Low      | Easy       | **Cleanup.** Minor API improvement for element tuple construction.                                                                   |
+| **GEP-012** | **Robust Model Composition**                  | Low      | Easy       | **Cleanup.** Handling advanced edge cases in `ModelA + ModelB` merging.                                                              |
+
+## Phase 3: Focused Expansion
+
+*Focus: Practical extensions that build directly on the core engine and schema.*
+
+| GEP         | Title                             | Impact   | Difficulty | Rationale                                                                                              |
+|:------------|:----------------------------------|:---------|:-----------|:-------------------------------------------------------------------------------------------------------|
+| **GEP-018** | **Relay Support**                 | **High** | Medium     | **Enterprise Feature.** Makes the API compatible with modern frontend clients (React Relay, Apollo).   |
+| **GEP-020** | **Modular Frontend Architecture** | Medium   | Medium     | **Maintainability.** Splitting the monolithic `viewer/index.html` into maintainable ES modules.        |
+| **GEP-029** | **Extraction Strategies**         | Medium   | Medium     | **Ergonomics.** Lightweight iterator/generator helpers (`scan`, `walk`, `listen`) or cookbook recipes. |
+
+## Phase 4: Exploratory & Spin-Off Track (Ideation / Brainstorming)
+
+*Focus: Ideas originating from exploratory brainstorming sessions. Rather than bloating the core `graphinate` package, these proposals should be treated as candidates for standalone companion packages, external integrations, or example recipes.*
+
+| GEP         | Title                                          | Recommended Vehicle                  | Rationale                                                                                                                     |
+|:------------|:-----------------------------------------------|:-------------------------------------|:------------------------------------------------------------------------------------------------------------------------------|
+| **GEP-026** | **Pluggable Visualization & Notebook Support** | Companion Package / Cookbook Recipes | Keeps core `graphinate` free of heavy frontend widget toolchains while enabling Jupyter/Cosmograph recipes.                   |
+| **GEP-027** | **Advanced Three.js Visualizations**           | Standalone Frontend / Demo Showcase  | Custom WebGL shaders, procedural cities, and time tunnels belong in a dedicated visualization showcase, not a Python ETL lib. |
+| **GEP-028** | **MCP Server Integration**                     | Companion Package (`graphinate-mcp`) | Ideal as a lightweight wrapper or example recipe exposing `GraphModel` and `GraphQLBuilder` to LLM agents via `fastmcp`.      |
+| **GEP-030** | **Node Type Taxonomy**                         | Cookbook Recipes / Domain Extensions | Universal ontologies (C4, Schema.org, Pygments) are best demonstrated as user-space models/recipes rather than core classes.  |
+
+---
+
+## Strategic Assessment of the GEP Trajectory
+
+### 1. Engineering Assessment: The Three Buckets
+
+The trajectory from **Graphinate 0.x** (a synchronous, decorator-based NetworkX/GraphQL builder) toward **Graphinate 2.0** (an observable, async-capable, type-safe Graph Synthesis Engine) is architecturally cohesive and well-differentiated in the Python ecosystem—provided that **implementation consolidation takes precedence over scope expansion**.
+
+Across the GEP archive, proposals fall naturally into three distinct tiers:
+
+1. **The Core Structural Spine (`GEP-010` → `GEP-032` → `GEP-012` → `GEP-024` → `GEP-023`)**:
+   - This is the true heart of Graphinate: moving from implicit `_id` naming magic to explicit `ParentId` dependency injection (**GEP-010**), compiling immutable validated models (**GEP-032**), decoupling traversal (`GraphEngine`, **GEP-024**) from storage (`NetworkxBuilder`), and unlocking `async def` generators (**GEP-023**).
+   - Every link in this chain directly enables the next and strengthens the library's core value proposition.
+2. **Boundary & Hygiene Refactorings (`GEP-002`, `GEP-014`, `GEP-016`, `GEP-017`, `GEP-019`, `GEP-020`, `GEP-031`)**:
+   - Practical engineering debt paydown: exposing `create_app()` (**GEP-017**), replacing fragile dynamic class construction in `GraphQLBuilder` with `strawberry.tools.create_type` and context injection (**GEP-014**), and keeping heavy dependencies optional (**GEP-002**).
+3. **Exploratory Ideation / Ambition Creep (`GEP-026`, `GEP-027`, `GEP-028`, `GEP-029`, `GEP-030`)**:
+   - These proposals originated in exploratory brainstorming sessions. While intellectually rich, features like custom Three.js shaders/procedural cities (**GEP-027**), universal class ontologies mapping Schema.org/C4/Pygments (**GEP-030**), and multi-engine WebGL abstractions (**GEP-026**) risk pulling a focused ~1,200-line Python library into maintaining a sprawling JavaScript/WebGL framework or ontology library ("Second-System Syndrome").
+   - **Strategic Decision:** Treat Tier 3 proposals as **Exploratory / Spin-Off Candidates** (separate high-level projects, plugin packages, or cookbook examples) so the core library stays lean and faithful to **GEP-001**.
+
+### 2. The Council's Opinion (By Pillar)
+
+Evaluating the codebase and GEP trajectory through the **7 Pillars of the Council Framework** (**GEP-001**):
+
+| Council Member                 | Verdict | Critique & Trajectory Guidance                                                                                                                                                                                                                                                                                                            |
+|:-------------------------------|:-------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **1. Symmetry (Noether)**      | **A-**  | `@model.node` supports `ParentId`, hierarchy, multiplicity, and deferred compilation (**GEP-010**, **GEP-032**). Future work in **GEP-024** should consider bringing symmetric dependency/scoping ergonomics to `@model.edge`, and ensuring edges can naturally target hierarchical (`unique=False`) nodes whose keys are lineage tuples. |
+| **2. Falsifiability (Popper)** |  **A**  | High branch coverage (~98%) and property-style tests provide a strong safety net. Every Standards Track GEP must be paired with falsifying regression tests before its status transitions to `Active`.                                                                                                                                    |
+| **3. Efficiency (Shannon)**    | **A-**  | `color.py` (**GEP-031**), `VariableNameManager` (`tools.py`), and $O(\text{deg}(v))$ GraphQL neighbor resolution are fast and lean. The primary remaining efficiency win is **GEP-002**: moving heavy packages (`matplotlib`, `strawberry-graphql`) out of mandatory core install dependencies into optional extras.                      |
+| **4. Safety (The Golem)**      | **A-**  | With **GEP-025** (HMAC-SHA256 signed IDs), **GEP-032** (immutable `model.compile()` clones), and isolated `GraphNodeType` schema enums, thread-safety and concurrency hazards have been substantially hardened—critical for Python 3.13t–3.15t free-threaded execution.                                                                   |
+| **5. Clarity (Feynman)**       |  **A**  | The `@model.node` / `@model.edge` declarative DSL remains simple and expressive. Completing **GEP-014** (explicit GraphQL schema generation with context injection) will remove the last major pocket of closure metaprogramming in `builders/graphql.py`.                                                                                |
+| **6. Consistency (Russell)**   | **A-**  | Case-insensitive parent resolution and explicit `_lineage` tuple propagation across recursion depths have unified behavior between `modeling.py` and `builders/networkx.py`.                                                                                                                                                              |
+| **7. Harmony (The Steward)**   | **A-**  | **The Dennis Point:** Resist building custom 3D shaders (**GEP-027**) or rigid taxonomies (**GEP-030**) inside core before the execution spine (`compile()` → `GraphEngine` → `abuild()`) is complete. Keep Graphinate focused on its mission: *"A declarative, Pythonic ETL engine for synthesizing graphs from hierarchical data."*     |
+
+---
+
+## Summary Priority Matrix (Core Library)
+
+| Priority | GEP         | Title                                      | Phase   |
+|:---------|:------------|:-------------------------------------------|:--------|
+| 1        | **GEP-024** | The Graph Engine                           | Phase 2 |
+| 2        | **GEP-014** | Explicit GraphQL Schema Generation         | Phase 2 |
+| 3        | **GEP-023** | Async Support                              | Phase 2 |
+| 4        | **GEP-019** | Offline Viewer Support                     | Phase 2 |
+| 5        | **GEP-031** | High-Performance Vectorized Operations     | Phase 2 |
+| 6        | **GEP-018** | Relay Support                              | Phase 3 |
+| 7        | **GEP-020** | Modular Frontend Architecture              | Phase 3 |
+| 8        | **GEP-029** | Extraction Strategies (Helpers / Recipes)  | Phase 3 |
+
+## Archive (Completed / Withdrawn / Superseded)
+
+| GEP         | Title                                  | Status            | Reason                                                                 |
+|:------------|:---------------------------------------|:------------------|:-----------------------------------------------------------------------|
+| **GEP-000** | Graphinate Enhancement Proposals       | **Active**        | Process definition.                                                    |
+| **GEP-001** | The Graphinate Mission                 | **Active**        | Mission statement.                                                     |
+| **GEP-002** | Modularization Strategy                | **Active**        | Architectural principle.                                               |
+| **GEP-007** | Theoretical Foundations                | **Active**        | Informational / Theory.                                                |
+| **GEP-010** | Explicit Dependency Injection          | **Active**        | Implemented explicit dependency injection using `ParentId`.            |
+| **GEP-013** | Stable ID Serialization                | **Withdrawn**     | `repr()` deemed sufficient and more robust for Python types.           |
+| **GEP-016** | CLI Argument Parsing & Path Safety     | **Active**        | Implemented Typer CLI with safe dynamic argument parsing & paths.      |
+| **GEP-017** | Decoupled Server Architecture          | **Active**        | Exposed `create_app()` ASGI factory in `graphinate.renderers.graphql`. |
+| **GEP-025** | Signed ID Serialization                | **Active**        | Implemented as an optional, opt-in HMAC-SHA256 signature layer.        |
+| **GEP-032** | GraphModel Compilation & Validation    | **Active**        | Implemented `GraphModel.compile()` and deferred validation.            |
+| **GEP-015** | Refactored Graph Population Strategies | **Superseded**    | Replaced by **GEP-024** (The Graph Engine).                            |
+| **GEP-022** | 2D Visualization Mode                  | **Superseded**    | Replaced by **GEP-026** (Pluggable Visualization).                     |
+| **GEP-027** | Advanced Three.js Visualizations       | **Informational** | Exploratory design concepts (Spin-Off / Showcase Track).               |
+
+

{graphinate-0.15.3 → graphinate-0.16.0}/design/proposals/GEP-010_Explicit_Dependency_Injection.md

@@ -5,10 +5,10 @@
 | **GEP**     | 10                            |
 | **Title**   | Explicit Dependency Injection |
 | **Author**  | Eran Rivlis                   |
-| **Status**  | Accepted                      |
+| **Status**  | Active                        |
 | **Type**    | Standards Track               |
 | **Created** | 2025-12-25                    |
-| **Updated** | 2026-06-21                    |
+| **Updated** | 2026-10-17                    |
 
 ## Abstract
 
@@ -144,16 +144,17 @@ and resolved within [modeling.py](file:///C:/dev/erivlis/graphinate/src/graphina
 * 2025-12-25: Initial Draft
 * 2026-06-21: Accepted Option 2 (Type Hinting) and implemented the injection engine.
 * 2026-06-22: Documented remaining structural and validation constraints as open issues/future work.
+* 2026-10-17: Resolved all 5 open issues (deferred compilation validation via GEP-032, immutable `compile()` clone, explicit `_lineage` tuple tracking for non-unique recursive nodes, case-insensitive lineage resolution, and removal of `NodeModel.parameters`).
 
-## Open Issues & Future Work
+## Resolved Issues (Formerly Open Issues)
 
-During the design review of the GEP-010 implementation, the Council of Principles identified the following remaining issues and areas for future work:
+During the initial design review of the GEP-010 implementation, the Council of Principles identified five follow-up items, all of which have now been resolved:
 
-1. **Eager Registration Validation:** Parameter validation (`_validate_node_dependency_registration`) currently runs eagerly at decorator execution time. This creates a strict topological import/decoration order constraint and prevents modular model composition (e.g., merging `ModelA + ModelB` where cross-dependencies are resolved only after composition). Future work will explore deferring validation to graph build time.
-2. **In-place Model Mutation (`rectify`):** The builder mutates the shared `GraphModel` instance in-place during the build phase via `rectify()`. This represents a potential concurrency side-effect. Future updates should clone the model or perform mutations on localized registries.
-3. **Recursive Lineage Namespace Collision:** In recursive structures (e.g., `folder -> folder`), overwriting the `folder_id` key in `kwargs` destroys the parent lineage chain, which causes parent ID resolution to fail when nodes are registered with `unique=False`. Passing an explicit lineage tuple during traversal will solve this collision.
-4. **Lineage Casing Asymmetry:** While injection lookup is case-insensitive, the early-break check in `_parent_node_id` remains case-sensitive, creating potential lineage pollution for mixed-case types.
-5. **Dead Code Cleanup (`NodeModel.parameters`):** The `parameters` attribute on `NodeModel` is currently obsolete and should be cleaned up.
+1. **Deferred Registration Validation (Resolved via GEP-032):** Parameter validation (`_validate_node_dependency_registration`) now runs during `GraphModel.compile()` rather than eagerly at decorator execution time, removing topological decoration-order constraints and enabling cross-model composition (`ModelA + ModelB`).
+2. **Immutable Model Compilation (Resolved via GEP-032):** `NetworkxBuilder` now compiles a clone of the `GraphModel` via `self.model.compile(...)` instead of mutating the shared `GraphModel` in-place via `rectify()`.
+3. **Recursive Lineage Namespace Collision (Resolved):** `_populate_nodes` and `_populate_node_type` now track an explicit `_lineage` tuple across recursion depth, preventing `folder -> folder` self-parenting key collisions when `unique=False`.
+4. **Lineage Casing Symmetry (Resolved):** `node_children_types`, `_validate_node_dependency_registration`, and `_parent_node_id` now resolve parent types case-insensitively.
+5. **Dead Code Cleanup (`NodeModel.parameters`) (Resolved):** Removed the obsolete `parameters` attribute from `NodeModel`.
 
 ## Copyright
 

{graphinate-0.15.3 → graphinate-0.16.0}/design/proposals/GEP-016_CLI_Argument_Parsing_and_Path_Safety.md

@@ -5,9 +5,10 @@
 | **GEP**     | 16                                 |
 | **Title**   | CLI Argument Parsing & Path Safety |
 | **Author**  | Eran Rivlis                        |
-| **Status**  | Draft                              |
+| **Status**  | Active                             |
 | **Type**    | Standards Track                    |
 | **Created** | 2025-12-25                         |
+| **Updated** | 2026-10-17                         |
 
 ## Abstract
 

{graphinate-0.15.3 → graphinate-0.16.0}/design/proposals/GEP-017_Decoupled_Server_Architecture.md

@@ -5,7 +5,7 @@
 | **GEP**     | 17                            |
 | **Title**   | Decoupled Server Architecture |
 | **Author**  | Eran Rivlis                   |
-| **Status**  | Draft                         |
+| **Status**  | Active                        |
 | **Type**    | Standards Track               |
 | **Created** | 2025-12-25                    |
 
@@ -28,13 +28,23 @@ This proposal suggests separating the app creation from the server execution.
 Refactor `renderers.graphql` to expose a factory function:
 
 ```python
-def create_app(schema: Schema, **kwargs) -> Starlette:
+def create_app(
+    graphql_schema: strawberry.Schema,
+    port: int = DEFAULT_PORT,
+    debug: bool = False,
+    **kwargs: Any,
+) -> Starlette:
     # ... construct and return the app ...
     return app
 
 
-def server(schema: Schema, **kwargs):
-    app = create_app(schema, **kwargs)
+def server(
+    graphql_schema: strawberry.Schema,
+    port: int = DEFAULT_PORT,
+    debug: bool = False,
+    **kwargs: Any,
+) -> None:
+    app = create_app(graphql_schema, port=port, debug=debug, **kwargs)
     uvicorn.run(app, ...)
 ```
 
@@ -42,3 +52,13 @@ def server(schema: Schema, **kwargs):
 
 The `server` function signature will remain the same, ensuring backward compatibility. The new `create_app` function
 will be an additive change.
+
+## Reference Implementation
+
+- [`src/graphinate/renderers/graphql.py`](file:///C:/dev/erivlis/graphinate/src/graphinate/renderers/graphql.py)
+- [`tests/graphinate/renderers/test_graphql_server.py`](file:///C:/dev/erivlis/graphinate/tests/graphinate/renderers/test_graphql_server.py)
+
+## Change Log
+
+- **2025-12-25:** Initial draft.
+- **2026-10-17:** Implemented `create_app` in `graphinate.renderers.graphql` and refactored `server()` to delegate to `create_app`. Updated status to `Active`.

{graphinate-0.15.3 → graphinate-0.16.0}/design/proposals/GEP-031_High_Performance_Vectorized_Operations.md

@@ -1,8 +1,14 @@
 # GEP-031: High-Performance Vectorized Operations
 
-*   **Status:** Draft
-*   **Type:** Standards Track
-*   **Created:** 2023-10-27
+| Field       | Value                                  |
+|:------------|:---------------------------------------|
+| **GEP**     | 31                                     |
+| **Title**   | High-Performance Vectorized Operations |
+| **Author**  | Eran Rivlis                            |
+| **Status**  | Draft                                  |
+| **Type**    | Standards Track                        |
+| **Created** | 2023-10-27                             |
+| **Updated** | 2026-10-17                             |
 
 ## Abstract
 

{graphinate-0.15.3 → graphinate-0.16.0}/design/proposals/GEP-032_GraphModel_Compilation_and_Validation_Lifecycle.md

@@ -5,10 +5,10 @@
 | **GEP**     | 32                                              |
 | **Title**   | GraphModel Compilation and Validation Lifecycle |
 | **Author**  | Eran Rivlis                                     |
-| **Status**  | Draft                                           |
+| **Status**  | Active                                          |
 | **Type**    | Standards Track                                 |
 | **Created** | 2026-06-22                                      |
-| **Updated** | 2026-06-22                                      |
+| **Updated** | 2026-10-17                                      |
 
 ## Abstract
 
@@ -132,10 +132,12 @@ This proposal serves as the structural glue between several critical enhancement
 ## Reference Implementation
 
 * **Source File:** [modeling.py](file:///C:/dev/erivlis/graphinate/src/graphinate/modeling.py)
-* **Builder Integration:** [builder.py](file:///C:/dev/erivlis/graphinate/src/graphinate/builders/builder.py)
+* **Builder Integration:** [networkx.py](file:///C:/dev/erivlis/graphinate/src/graphinate/builders/networkx.py)
 
 ---
 
 ## Change Log
 
 * 2026-06-22: Initial Draft outlining the compilation phases, late validation, and synergies with GEP-010, GEP-012, and GEP-024.
+* 2026-10-17: Implemented `GraphModel.compile()`, `_validate_structural_dependencies()`, deferred dependency validation, and immutable model compilation in `NetworkxBuilder`.
+

graphinate-0.16.0/docs/usage/cli.md

@@ -0,0 +1,56 @@
+---
+title: CLI
+icon: lucide/command
+---
+# CLI
+
+## Commands
+
+``` shell
+Usage: python -m graphinate [OPTIONS] COMMAND [ARGS]...
+
+Options:
+  --help  Show this message and exit.
+
+Commands:
+  save
+  server
+```
+
+### Save
+
+```console
+Usage: python -m graphinate save [OPTIONS]
+
+Options:
+  -m, --model MODEL       A GraphModel instance reference {module-
+                          name}:{GraphModel-instance-variable-name} For example,
+                          given var `model=GraphModel()` defined in app.py file,
+                          then the reference should be app:model
+  --debug / --no-debug    Enable debug logging.  [env var: GRAPHINATE_DEBUG]
+  --help                  Show this message and exit.
+```
+
+### Server
+
+!!! tip
+
+    requires the `server` extra to be installed.
+
+      ```shell
+      pip install graphinate[server]
+      ```
+
+```console
+Usage: python -m graphinate server [OPTIONS]
+
+Options:
+  -m, --model MODEL            A GraphModel instance reference {module-
+                               name}:{GraphModel-instance-variable-name} For example,
+                               given var `model=GraphModel()` defined in app.py file,
+                               then the reference should be app:model
+  -p, --port INTEGER           Port number.
+  -b, --browse / --no-browse   Open web browser on start.
+  --debug / --no-debug         Enable debug logging.  [env var: GRAPHINATE_DEBUG]
+  --help                       Show this message and exit.
+```

{graphinate-0.15.3 → graphinate-0.16.0}/docs/usage/lib.md

@@ -21,7 +21,7 @@ icon: lucide/package
 
       The `GraphModel` Class which is used to declaratively register, Edge and/or Node data supplier functions.
       Using the [`GraphModel.node()`](../reference/graphinate/modeling.md#graphinate.modeling.GraphModel.node)
-      and [`GraphMode.edge()`](../reference/graphinate/modeling.md#graphinate.modeling.GraphModel.edge) decorators.
+      and [`GraphModel.edge()`](../reference/graphinate/modeling.md#graphinate.modeling.GraphModel.edge) decorators.
 
 ### Builders
 

{graphinate-0.15.3 → graphinate-0.16.0}/pyproject.toml

@@ -1,10 +1,12 @@
 [project]
 name = "Graphinate"
-version = "0.15.3"
+version = "0.16.0"
 description = "Graphinate. Data to Graphs."
 authors = [
     { name = "Eran Rivlis", email = "eran@rivlis.info" },
 ]
+license = "LGPL-3.0-or-later"
+license-files = ["LICENSE"]
 readme = "README.md"
 requires-python = ">=3.11"
 classifiers = [

{graphinate-0.15.3 → graphinate-0.16.0}/src/graphinate/.agents/skills/graphinate/SKILL.md

@@ -103,9 +103,9 @@ print(mermaid_string)
 ## 5. Gotchas & Best Practices
 
 - **The Command Center (`graphinate.cli`)**: For quick builds or serving, use the CLI:
-    - `graphinate build --model <path/to/model.py>`
-    - `graphinate serve --model <path/to/model.py>`
-- **The Broadcaster (`graphinate.server`)**: The `serve` command requires optional dependencies. If it fails, the user
+    - `graphinate save --model <module:model>`
+    - `graphinate server --model <module:model>`
+- **The Broadcaster (`graphinate.server`)**: The `server` command requires optional dependencies. If it fails, the user
   needs to run:
   ```bash
   pip install "graphinate[server]"

{graphinate-0.15.3 → graphinate-0.16.0}/src/graphinate/builders/graphql.py

@@ -28,6 +28,7 @@ from ..converters import (
 )
 from ..enums import GraphType
 from ..modeling import GraphModel
+from ..tools import VariableNameManager
 from .networkx import NetworkxBuilder
 
 
@@ -173,7 +174,7 @@ class GraphQLBuilder(NetworkxBuilder):
         number_of_isolates = 'number_of_isolates'
         number_connected_components = 'number_connected_components'
         number_strongly_connected_components = 'number_strongly_connected_components'
-        number_weakly_connected_components = ' number_weakly_connected_components'
+        number_weakly_connected_components = 'number_weakly_connected_components'
         number_attracting_components = 'number_attracting_components'
         node_connectivity = 'node_connectivity'
         transitivity = 'transitivity'
@@ -193,6 +194,7 @@ class GraphQLBuilder(NetworkxBuilder):
     def __init__(self, model: GraphModel, graph_type: GraphType = GraphType.Graph):
         super().__init__(model, graph_type)
         self._node_value_graphql_type_supplier: Callable[[str], StrawberryType | None] | None = None
+        self._cached_graphql_types: dict[str, type[GraphQLBuilder.GraphNode]] | None = None
 
     @staticmethod
     def add_field_resolver(class_dict: dict, field_name: str, resolver: Callable, graphql_type: Any | None = None):
@@ -248,8 +250,9 @@ class GraphQLBuilder(NetworkxBuilder):
 
     @staticmethod
     def _graphql_enum(name: str, values: list[str]) -> EnumType:
+        name_manager = VariableNameManager()
         return strawberry.enum(
-            Enum(name, {v: v for v in values}),
+            Enum(name, {name_manager.make_valid(v): v for v in values}),
             name=name,
             description=f"{name} Enumeration"
         )
@@ -263,50 +266,56 @@ class GraphQLBuilder(NetworkxBuilder):
         from strawberry.types.enum import EnumValue
 
         types_to_populate = node_types if node_types else ['node']
+        name_manager = VariableNameManager()
+
+        self.GraphNodeType.__strawberry_definition__.values.clear()
 
         for v in types_to_populate:
-            if v not in self.GraphNodeType._member_names_:
-                self.GraphNodeType._member_names_.append(v)
-                self.GraphNodeType._member_map_[v] = v
-                self.GraphNodeType._value2member_map_[v] = v
-
-                self.GraphNodeType.__strawberry_definition__.values.append(
-                    EnumValue(
-                        name=v,
-                        value=v,
-                        description=f"Graph Node Type: {v}"
-                    )
+            member_name = name_manager.make_valid(v)
+            if member_name not in self.GraphNodeType._member_names_:
+                self.GraphNodeType._member_names_.append(member_name)
+            self.GraphNodeType._member_map_[member_name] = v
+            self.GraphNodeType._value2member_map_[v] = v
+
+            self.GraphNodeType.__strawberry_definition__.values.append(
+                EnumValue(
+                    name=member_name,
+                    value=v,
+                    description=f"Graph Node Type: {v}"
                 )
-
+            )
 
     @property
-    @functools.lru_cache
     def _graphql_types(self) -> dict[str, type['GraphQLBuilder.GraphNode']]:
+        if self._cached_graphql_types is not None:
+            return self._cached_graphql_types
+
         node_types = list(self._graph.graph['node_types'].keys())
 
         self._populate_graph_node_type_enum(node_types)
 
-        def neighbors_resolver():
+        def neighbors_resolver(current_node_type: str):
             graph = self._graph
 
-            children_types = set(self._children_types(self.model, node_type))
+            children_types = set(self._children_types(self.model, current_node_type))
 
             def node_neighbors(self,
                                type: 'GraphQLBuilder.GraphNodeType | None' = None,
                                children: bool = False) -> list['GraphQLBuilder.GraphNode']:
                 node = decode_node_id(self.id)
-                items = (GraphQLBuilder._graph_node(graphql_types[d['type']], n, d)
-                         for n, d in graph.nodes(data=True)
-                         if n in graph.neighbors(node))
+                items = (
+                    GraphQLBuilder._graph_node(graphql_types[(d := graph.nodes[n])['type']], n, d)
+                    for n in graph.neighbors(node)
+                )
 
                 if type is not None:
-                    items = (item for item in items if item.type == type)
+                    target_type = getattr(type, 'value', type)
+                    items = (item for item in items if item.type == target_type)
 
                 if children and children_types:
                     items = (item for item in items if item.type in children_types)
 
-                items = list(items)
-                return items
+                return list(items)
 
             return node_neighbors
 
@@ -320,10 +329,11 @@ class GraphQLBuilder(NetworkxBuilder):
 
             return node_edges
 
+        class_name_manager = VariableNameManager()
         # Create classes for nodes according to their type
         graphql_types: dict[str, type[GraphQLBuilder.GraphNode]] = {}
         for node_type in node_types:
-            class_name = node_type.capitalize()
+            class_name = class_name_manager.make_valid(node_type.capitalize())
             bases = (GraphQLBuilder.GraphNode,)
             class_dict = {
                 '__doc__': f"A {class_name} Graph Node",
@@ -336,13 +346,14 @@ class GraphQLBuilder(NetworkxBuilder):
             ):
                 class_dict['value'] = list[value_graphql_type]
 
-            self.add_field_resolver(class_dict, 'neighbors', neighbors_resolver())
+            self.add_field_resolver(class_dict, 'neighbors', neighbors_resolver(node_type))
             self.add_field_resolver(class_dict, 'edges', edges_resolver())
 
             # noinspection PyTypeChecker
             graphql_type: type[GraphQLBuilder.GraphNode] = type(class_name, bases, class_dict)
             graphql_types[node_type] = GraphQLBuilder._graphql_type(node_type, graphql_type)
 
+        self._cached_graphql_types = graphql_types
         return graphql_types
 
     def _graphql_query(self):  # noqa: C901
@@ -434,8 +445,9 @@ class GraphQLBuilder(NetworkxBuilder):
         # endregion
 
         # region - Defining GraphQL Query Class dict - fields for GraphQL types implementing 'GraphNode' interface
+        field_name_manager = VariableNameManager()
         for node_type, graphql_type in self._graphql_types.items():
-            field_name = inflection.plural(node_type)
+            field_name = field_name_manager.make_valid(inflection.plural(node_type))
             resolver = graph_nodes_resolver(graphql_type, node_type)
             self.add_field_resolver(query_class_dict, field_name, resolver)
 
@@ -521,6 +533,7 @@ class GraphQLBuilder(NetworkxBuilder):
         Returns:
             Strawberry GraphQL Schema
         """
+        self._cached_graphql_types = None
         super().build(**kwargs)
 
         self._node_value_graphql_type_supplier = node_value_graphql_type_supplier