graphforge 0.1.0__tar.gz

graphforge-0.1.0/.github/workflows/publish.yaml

@@ -0,0 +1,16 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv build
+      - run: uv publish

graphforge-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

graphforge-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

graphforge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Spencer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

graphforge-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: graphforge
+Version: 0.1.0
+Summary: Composable graph tooling for analysis, construction, and refinement
+Project-URL: Homepage, https://github.com/your-org/graphforge
+Project-URL: Repository, https://github.com/your-org/graphforge
+Project-URL: Issues, https://github.com/your-org/graphforge/issues
+Author: David Spencer
+License: MIT
+License-File: LICENSE
+Keywords: analysis,graph,opencypher,pydantic
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.6
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://img.shields.io/pypi/v/graphforge?style=for-the-badge" alt="PyPI version" />
+  <img src="https://img.shields.io/badge/python-3.10+-3776ab?style=for-the-badge&logo=python&logoColor=white" alt="Python" />
+  <img src="https://img.shields.io/badge/license-MIT-22c55e?style=for-the-badge" alt="License" />
+  <img src="https://img.shields.io/badge/pydantic-2.6+-e92063?style=for-the-badge&logo=pydantic&logoColor=white" alt="Pydantic" />
+  <img src="https://img.shields.io/badge/openCypher%20TCK%20target-2024.2-6c4f7c?style=for-the-badge" alt="openCypher TCK target" />
+</p>
+
+<h1 align="center">GraphForge</h1>
+<p align="center">
+  <strong>Composable graph tooling for analysis, construction, and refinement</strong>
+</p>
+
+<p align="center">
+  A lightweight, embedded, openCypher-compatible graph engine for research and investigative workflows
+</p>
+
+---
+
+## Why GraphForge?
+
+Modern data science and ML workflows increasingly produce **graph-shaped data**—entities and relationships extracted from text, tables, and LLM outputs. Yet practitioners face a painful choice:
+
+| | NetworkX | Production DBs (Neo4j, Memgraph) |
+|:---|:---|:---|
+| **Durability** | Manual serialization only | ✓ Persistent |
+| **Query language** | None | Cypher |
+| **Operational overhead** | Minimal | High (services, config) |
+| **Notebook-friendly** | ✓ | ✗ |
+| **Iterative analysis** | ✓ | Poor |
+
+**GraphForge** fills the gap—embedded, durable, and declarative—without running external services.
+
+> *We are not building a database for applications.*  
+> *We are building a graph execution environment for thinking.*
+
+---
+
+## Features
+
+- **Embedded & local-first** — No server, no daemon. Runs entirely inside your Python process.
+- **openCypher subset** — Declarative pattern matching with semantic correctness validated against the TCK.
+- **Graph-native execution** — Adjacency-based traversal, not relational joins.
+- **Durable but disposable** — Persist graphs across restarts; treat them as analytical artifacts.
+- **Python-first** — Designed for notebooks, scripts, and agentic pipelines.
+
+### Planned v1 Scope
+
+- **MATCH** (nodes, relationships, directionality)
+- **WHERE** (boolean logic, comparisons, property access)
+- **RETURN**, **LIMIT**, **SKIP**
+- Node and relationship materialization
+- Optional Pydantic-backed data models for validation
+
+---
+
+## Installation
+
+```bash
+# Using uv (recommended)
+uv add graphforge
+
+# Using pip
+pip install graphforge
+```
+
+**Requirements:** Python 3.10+
+
+---
+
+## Quick Start
+
+```python
+from graphforge import GraphForge
+
+# Create a graph (API in development)
+db = GraphForge("my-graph.db")
+
+# Execute openCypher queries
+rows = db.execute("""
+  MATCH (n:Person)
+  WHERE n.age > 30
+  RETURN n.name
+  LIMIT 5
+""")
+```
+
+> **Note:** GraphForge is early in development. The core API and storage layer are being built out per the [requirements document](docs/0-requirements.md).
+
+---
+
+## Design Principles
+
+- **Spec-driven correctness** — openCypher semantics over performance.
+- **Deterministic & reproducible** — Stable behavior across runs.
+- **Inspectable** — Query plans, storage layout, and execution behavior are observable.
+- **Replaceable internals** — Minimal operational overhead, stable APIs.
+
+---
+
+## Links
+
+- [Requirements document](docs/0-requirements.md) — Full scope, TCK strategy, and design rationale
+- [openCypher AST spec](docs/open_cypher_ast_logical_plan_spec_v_1.md)
+- [Runtime value model](docs/runtime_value_model_graph_execution_v_1.md)
+
+---
+
+## License
+
+MIT © David Spencer

graphforge-0.1.0/README.md

@@ -0,0 +1,111 @@
+<p align="center">
+  <img src="https://img.shields.io/pypi/v/graphforge?style=for-the-badge" alt="PyPI version" />
+  <img src="https://img.shields.io/badge/python-3.10+-3776ab?style=for-the-badge&logo=python&logoColor=white" alt="Python" />
+  <img src="https://img.shields.io/badge/license-MIT-22c55e?style=for-the-badge" alt="License" />
+  <img src="https://img.shields.io/badge/pydantic-2.6+-e92063?style=for-the-badge&logo=pydantic&logoColor=white" alt="Pydantic" />
+  <img src="https://img.shields.io/badge/openCypher%20TCK%20target-2024.2-6c4f7c?style=for-the-badge" alt="openCypher TCK target" />
+</p>
+
+<h1 align="center">GraphForge</h1>
+<p align="center">
+  <strong>Composable graph tooling for analysis, construction, and refinement</strong>
+</p>
+
+<p align="center">
+  A lightweight, embedded, openCypher-compatible graph engine for research and investigative workflows
+</p>
+
+---
+
+## Why GraphForge?
+
+Modern data science and ML workflows increasingly produce **graph-shaped data**—entities and relationships extracted from text, tables, and LLM outputs. Yet practitioners face a painful choice:
+
+| | NetworkX | Production DBs (Neo4j, Memgraph) |
+|:---|:---|:---|
+| **Durability** | Manual serialization only | ✓ Persistent |
+| **Query language** | None | Cypher |
+| **Operational overhead** | Minimal | High (services, config) |
+| **Notebook-friendly** | ✓ | ✗ |
+| **Iterative analysis** | ✓ | Poor |
+
+**GraphForge** fills the gap—embedded, durable, and declarative—without running external services.
+
+> *We are not building a database for applications.*  
+> *We are building a graph execution environment for thinking.*
+
+---
+
+## Features
+
+- **Embedded & local-first** — No server, no daemon. Runs entirely inside your Python process.
+- **openCypher subset** — Declarative pattern matching with semantic correctness validated against the TCK.
+- **Graph-native execution** — Adjacency-based traversal, not relational joins.
+- **Durable but disposable** — Persist graphs across restarts; treat them as analytical artifacts.
+- **Python-first** — Designed for notebooks, scripts, and agentic pipelines.
+
+### Planned v1 Scope
+
+- **MATCH** (nodes, relationships, directionality)
+- **WHERE** (boolean logic, comparisons, property access)
+- **RETURN**, **LIMIT**, **SKIP**
+- Node and relationship materialization
+- Optional Pydantic-backed data models for validation
+
+---
+
+## Installation
+
+```bash
+# Using uv (recommended)
+uv add graphforge
+
+# Using pip
+pip install graphforge
+```
+
+**Requirements:** Python 3.10+
+
+---
+
+## Quick Start
+
+```python
+from graphforge import GraphForge
+
+# Create a graph (API in development)
+db = GraphForge("my-graph.db")
+
+# Execute openCypher queries
+rows = db.execute("""
+  MATCH (n:Person)
+  WHERE n.age > 30
+  RETURN n.name
+  LIMIT 5
+""")
+```
+
+> **Note:** GraphForge is early in development. The core API and storage layer are being built out per the [requirements document](docs/0-requirements.md).
+
+---
+
+## Design Principles
+
+- **Spec-driven correctness** — openCypher semantics over performance.
+- **Deterministic & reproducible** — Stable behavior across runs.
+- **Inspectable** — Query plans, storage layout, and execution behavior are observable.
+- **Replaceable internals** — Minimal operational overhead, stable APIs.
+
+---
+
+## Links
+
+- [Requirements document](docs/0-requirements.md) — Full scope, TCK strategy, and design rationale
+- [openCypher AST spec](docs/open_cypher_ast_logical_plan_spec_v_1.md)
+- [Runtime value model](docs/runtime_value_model_graph_execution_v_1.md)
+
+---
+
+## License
+
+MIT © David Spencer