graph-ted-db 0.1.0__tar.gz

graph_ted_db-0.1.0/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to graph-ted-db are listed here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Until 1.0.0, a minor
+version may include breaking changes; they are called out under **Changed**.
+
+## [Unreleased]
+
+## [0.1.0]
+
+First public release.
+
+### Security
+
+- Unauthenticated `GET /health` returns only `ok` and the library version.
+  The graph name, id, counts and problem counts are on `GET /info`, which
+  needs the token when one is set.
+- `serve` warns when it listens off loopback, even with a token.
+
+### Added
+
+- `GraphStore` and `init_graph`: a property graph stored in a folder of
+  sharded JSONL files, opened and queried in-process with no server.
+- Record types exported from `graph_ted_db`: `NodeRecord`, `EdgeRecord`,
+  `VectorRecord`, `Tombstone`.
+- Nodes, edges and embedding vectors: `make_node` / `make_edge`, `put_*`,
+  `get_*`, `iter_nodes` / `iter_edges`, `delete_*` (tombstones).
+- Per-record last-write-wins, and reading of sync-tool conflict copies
+  (OneDrive- and Dropbox-style names, rclone bisync `.conflictN` / `..pathN`)
+  so a graph folder can be shared through a file-sync service. Multiple
+  devices can add and edit at the same time; concurrent edits to the same
+  record resolve to the latest version.
+- On-disk format version 2 (`docs/format.md`): each writer appends only to
+  its own files (`<shard>.<writer>.jsonl`, `meta/deleted.<writer>.jsonl`),
+  with a random writer id kept in local app data and a registration file in
+  `meta/writers/`. Versions are ordered by a hybrid logical clock
+  `(updated_at, counter, writer)`. Version 1 folders are read, and upgraded on
+  the first write.
+- Torn-tail repair touches only this writer's own files; other writers' files
+  are never modified, and an unterminated last line is skipped and reported.
+  `compact` refuses to run on a shared store (`SharedStoreError`).
+- `GraphStore.problems()`, `graph-ted-db info --check`, a `problems` object
+  in `/health` (counts only), and a warning on open, for skipped lines,
+  other writers' unterminated files, cloud-only placeholders and empty record
+  files. `doctor` lists them.
+- `graph-ted-db export` / `import` and `GraphStore.export` /
+  `import_export`: back up the current state to one JSONL file and restore
+  it into a new graph. Backup guidance in `docs/backup.md`.
+- openCypher: `count(*)`, and unaliased `RETURN` expressions (the column is
+  named by its source text, e.g. `b.name`).
+- Opening a graph above 250,000 records logs how long it took and points to
+  the Graph size docs.
+- Crash safety: one flush and fsync per multi-record transaction, replay of
+  an interrupted transaction on open, torn-line repair.
+- `GraphStore.execute` / `execute_many`: a documented subset of openCypher,
+  with `CypherError` (and its source position) for anything outside it.
+- NetworkX-style helpers: `add_node`, `add_edge`, `neighbors`, `has_node`,
+  `has_edge`, `remove_node`, `remove_edge`, `nodes`, `edges`.
+- `graph-ted-db` CLI (alias `graphted-db`): `init`, `info`, node and edge
+  CRUD, `compact`, `doctor` (repairs torn lines and reports dangling edges;
+  `--fix` tombstones them), `cypher`, `serve`, `--version`.
+- `updated_by` (record author) is empty by default and never taken from the
+  OS login name. Set it with `--by` / `--updated-by` on CLI writes, the
+  `GRAPH_TED_DB_UPDATED_BY` environment variable, or `updated_by=` in Python.
+- `graph-ted-db serve`: optional localhost JSON-over-HTTP endpoint
+  (`/health`, `/info`, `/cypher`, atomic `statements` batches). Binding
+  beyond loopback requires a token. `/health`, the one route open without a
+  token, does not include the folder path.
+- Optional Graphiti driver (`graph_ted_db.driver.GraphTedDbDriver`), in-process
+  or over HTTP.
+- Documentation site with `llms.txt` and `llms-full.txt`.
+
+[Unreleased]: https://github.com/graph-ted/graph-ted-db/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/graph-ted/graph-ted-db/releases/tag/v0.1.0

graph_ted_db-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 graph-ted-db contributors
+
+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.

graph_ted_db-0.1.0/MANIFEST.in

@@ -0,0 +1,10 @@
+# Meta package is built from packages/graphted, not shipped inside graph-ted-db.
+prune packages
+# The sdist is the library plus README, LICENSE and CHANGELOG. Tests need the
+# repo's scripts, docs and fixtures, so they stay in git, not in the sdist.
+prune tests
+prune reports
+prune docs
+prune scripts
+include CHANGELOG.md
+global-exclude *.py[cod] __pycache__

graph_ted_db-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: graph-ted-db
+Version: 0.1.0
+Summary: Local property-graph storage for Python. Data lives in a folder; open and query it in-process, with no database server for the default path.
+Author: graph-ted-db contributors
+License-Expression: MIT
+Project-URL: Homepage, https://graph-ted.com/graph-ted-db/
+Project-URL: Documentation, https://graph-ted.com/graph-ted-db/docs/
+Project-URL: Source, https://github.com/graph-ted/graph-ted-db
+Project-URL: Issues, https://github.com/graph-ted/graph-ted-db/issues
+Project-URL: Changelog, https://github.com/graph-ted/graph-ted-db/blob/main/CHANGELOG.md
+Keywords: graph,property-graph,graph-database,opencypher,local-first,embedded
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Database :: Database Engines/Servers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://graph-ted.com/graph-ted-db/docs/assets/logo-readme.png" alt="graph-ted-db" width="340" height="116">
+</p>
+
+<!-- Images and links use absolute URLs so they render on PyPI. The logo is served by the docs site. -->
+
+# graph-ted-db
+
+Local property-graph storage for Python. Your data lives in a folder on disk; open it from your process, query it in-process, and optionally sync that folder like any other files. No database server to run for the default path.
+
+**Package:** `graph-ted-db` · **Import:** `graph_ted_db` · **Repo:** [graph-ted/graph-ted-db](https://github.com/graph-ted/graph-ted-db) · **License:** MIT
+
+> Status: the public API and on-disk format below are what we ship. `pip install graph-ted-db` is the intended install; until the package is on PyPI, use a checkout (`pip install -e .`) or a wheel path.
+
+---
+
+## Install
+
+```bash
+pip install graph-ted-db
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+```python
+from graph_ted_db import GraphStore, init_graph
+
+init_graph("./my-graph", name="demo", exist_ok=True)
+g = GraphStore.open("./my-graph")
+
+alice = g.make_node(labels=["Person"], props={"name": "Alice"})
+bob = g.make_node(labels=["Person"], props={"name": "Bob"})
+g.make_edge(type="KNOWS", from_id=alice.id, to_id=bob.id)
+
+print(g.get_node(alice.id).props["name"])
+```
+
+CLI:
+
+```bash
+graph-ted-db init ./my-graph --name demo --exist-ok
+graph-ted-db put-node ./my-graph --label Person --prop name=Alice
+graph-ted-db ls-nodes ./my-graph
+```
+
+`graphted-db` is an alias for the same command.
+
+Optional HTTP (localhost only by default; see [HTTP docs](https://graph-ted.com/graph-ted-db/docs/http/)):
+
+```bash
+graph-ted-db serve ./my-graph
+# in another terminal:
+curl -s http://127.0.0.1:8099/health
+curl -s http://127.0.0.1:8099/cypher -H 'Content-Type: application/json' \
+  -d '{"query":"MATCH (n:Person) RETURN n.name AS name"}'
+```
+
+## Features
+
+- **Folder = database** — nodes, edges, and embeddings as sharded JSONL; readable, backupable, syncable
+- **In-process API** — `put` / `get` / `iter` / `delete` without opening a network port
+- **openCypher queries** — `g.execute(...)` runs a documented subset of openCypher for graph-pattern queries ([openCypher subset](https://graph-ted.com/graph-ted-db/docs/cypher/))
+- **Optional HTTP** — localhost endpoint for openCypher queries when another process needs the store ([HTTP docs](https://graph-ted.com/graph-ted-db/docs/http/))
+- **Sync-friendly** — multiple devices can write at once; last-write-wins per record; conflict-copy shards merged on read
+- **NetworkX-style helpers** — `add_node`, `add_edge`, `neighbors`, and related methods on the same `GraphStore` (no algorithm suite)
+
+## What it is and isn't
+
+**It is:**
+
+- A Python library that stores a property graph (nodes, edges, properties, embeddings) as plain JSONL files in one folder.
+- In-process: open, read, write and query from your own Python process. No server to install or run.
+- A documented subset of openCypher, plus NetworkX-style helpers.
+- Sync-friendly across devices: multiple devices can add and edit at the same time; concurrent edits to the same record resolve to the latest version. The folder can live in OneDrive, Dropbox or an `rclone bisync` folder (see [Sharing](https://graph-ted.com/graph-ted-db/docs/sharing/)).
+- Small: no runtime dependencies beyond the Python standard library.
+
+**It isn't:**
+
+- A database server, a hosted service or a multi-tenant system. The optional HTTP endpoint is for local processes on the same machine.
+- Encrypted. Files are ordinary files; protect them with disk encryption and OS permissions.
+- A complete Cypher implementation or a Neo4j replacement. Unsupported clauses fail with an error rather than being ignored.
+- A graph-algorithm library. Use NetworkX or similar on exported data.
+- Built for very large graphs. The whole graph is loaded into memory when it opens; see the tested sizes in [Overview](https://graph-ted.com/graph-ted-db/docs/overview/).
+- Stable across minor versions before 1.0 (see [Versioning](#versioning)).
+- Telemetry-enabled. It makes no network calls of its own.
+
+## When to use it
+
+Good fit for prototypes, local tools, agents, and small trusted groups that want a property graph next to the app.
+
+Choose a server graph database when you need multi-tenant hosting, fine-grained remote auth, or a complete query language and enterprise feature set out of the box.
+
+## Security
+
+Data is stored as ordinary files. The library does **not** encrypt the graph folder. Security matches your environment: disk or volume encryption, OS account permissions, backups, sync tools, and whether anything listens on the network.
+
+- **Airgapped host + encrypted volume** — can be very strong; treat that environment as your boundary.
+- **Synced or shared folders** — anyone with access to the folder can read what you stored (including properties).
+- **HTTP serve** — defaults to localhost; binding beyond loopback requires an explicit host and a token. That protects the port, not the files on disk.
+
+Choose storage and network to match how sensitive the data is.
+
+## Documentation
+
+Docs: [graph-ted.com/graph-ted-db/docs](https://graph-ted.com/graph-ted-db/docs/), built from the `docs/` folder in this repository. Preview locally: see [PREVIEW.md](https://github.com/graph-ted/graph-ted-db/blob/main/PREVIEW.md).
+
+| Doc | Contents |
+|-----|----------|
+| [Overview](https://graph-ted.com/graph-ted-db/docs/overview/) | Product overview |
+| [On-disk format](https://graph-ted.com/graph-ted-db/docs/format/) | On-disk layout |
+| [openCypher subset](https://graph-ted.com/graph-ted-db/docs/cypher/) | Supported openCypher subset |
+| [Trademarks](https://graph-ted.com/graph-ted-db/docs/trademarks/) | Trademarks |
+| [HTTP](https://graph-ted.com/graph-ted-db/docs/http/) | Local HTTP serve |
+
+## Trademarks
+
+openCypher is a trademark of Neo4j, Inc. Other names are trademarks of their respective owners; no endorsement implied. See [Trademarks](https://graph-ted.com/graph-ted-db/docs/trademarks/).
+
+## Versioning
+
+Pre-1.0 (`0.1.0`). Until 1.0.0, minor versions may include breaking changes; they are noted in release notes. From 1.0.0, breaking changes bump the major version.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Feedback and issues
+
+- **Bugs, enhancement requests, docs problems:** [open an issue](https://github.com/graph-ted/graph-ted-db/issues/new/choose) using one of the forms.
+- **Questions and ideas:** [Discussions](https://github.com/graph-ted/graph-ted-db/discussions).
+- **Security vulnerabilities:** report privately as described in [SECURITY.md](https://github.com/graph-ted/graph-ted-db/blob/main/SECURITY.md), never in a public issue.
+
+Contributing: see [CONTRIBUTING.md](https://github.com/graph-ted/graph-ted-db/blob/main/CONTRIBUTING.md).
+
+## Related
+
+graph-ted-db is the local store for the graph-ted toolkit ([graph-ted.com](https://graph-ted.com/)). This repository is the database library only.

graph_ted_db-0.1.0/README.md

@@ -0,0 +1,142 @@
+<p align="center">
+  <img src="https://graph-ted.com/graph-ted-db/docs/assets/logo-readme.png" alt="graph-ted-db" width="340" height="116">
+</p>
+
+<!-- Images and links use absolute URLs so they render on PyPI. The logo is served by the docs site. -->
+
+# graph-ted-db
+
+Local property-graph storage for Python. Your data lives in a folder on disk; open it from your process, query it in-process, and optionally sync that folder like any other files. No database server to run for the default path.
+
+**Package:** `graph-ted-db` · **Import:** `graph_ted_db` · **Repo:** [graph-ted/graph-ted-db](https://github.com/graph-ted/graph-ted-db) · **License:** MIT
+
+> Status: the public API and on-disk format below are what we ship. `pip install graph-ted-db` is the intended install; until the package is on PyPI, use a checkout (`pip install -e .`) or a wheel path.
+
+---
+
+## Install
+
+```bash
+pip install graph-ted-db
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+```python
+from graph_ted_db import GraphStore, init_graph
+
+init_graph("./my-graph", name="demo", exist_ok=True)
+g = GraphStore.open("./my-graph")
+
+alice = g.make_node(labels=["Person"], props={"name": "Alice"})
+bob = g.make_node(labels=["Person"], props={"name": "Bob"})
+g.make_edge(type="KNOWS", from_id=alice.id, to_id=bob.id)
+
+print(g.get_node(alice.id).props["name"])
+```
+
+CLI:
+
+```bash
+graph-ted-db init ./my-graph --name demo --exist-ok
+graph-ted-db put-node ./my-graph --label Person --prop name=Alice
+graph-ted-db ls-nodes ./my-graph
+```
+
+`graphted-db` is an alias for the same command.
+
+Optional HTTP (localhost only by default; see [HTTP docs](https://graph-ted.com/graph-ted-db/docs/http/)):
+
+```bash
+graph-ted-db serve ./my-graph
+# in another terminal:
+curl -s http://127.0.0.1:8099/health
+curl -s http://127.0.0.1:8099/cypher -H 'Content-Type: application/json' \
+  -d '{"query":"MATCH (n:Person) RETURN n.name AS name"}'
+```
+
+## Features
+
+- **Folder = database** — nodes, edges, and embeddings as sharded JSONL; readable, backupable, syncable
+- **In-process API** — `put` / `get` / `iter` / `delete` without opening a network port
+- **openCypher queries** — `g.execute(...)` runs a documented subset of openCypher for graph-pattern queries ([openCypher subset](https://graph-ted.com/graph-ted-db/docs/cypher/))
+- **Optional HTTP** — localhost endpoint for openCypher queries when another process needs the store ([HTTP docs](https://graph-ted.com/graph-ted-db/docs/http/))
+- **Sync-friendly** — multiple devices can write at once; last-write-wins per record; conflict-copy shards merged on read
+- **NetworkX-style helpers** — `add_node`, `add_edge`, `neighbors`, and related methods on the same `GraphStore` (no algorithm suite)
+
+## What it is and isn't
+
+**It is:**
+
+- A Python library that stores a property graph (nodes, edges, properties, embeddings) as plain JSONL files in one folder.
+- In-process: open, read, write and query from your own Python process. No server to install or run.
+- A documented subset of openCypher, plus NetworkX-style helpers.
+- Sync-friendly across devices: multiple devices can add and edit at the same time; concurrent edits to the same record resolve to the latest version. The folder can live in OneDrive, Dropbox or an `rclone bisync` folder (see [Sharing](https://graph-ted.com/graph-ted-db/docs/sharing/)).
+- Small: no runtime dependencies beyond the Python standard library.
+
+**It isn't:**
+
+- A database server, a hosted service or a multi-tenant system. The optional HTTP endpoint is for local processes on the same machine.
+- Encrypted. Files are ordinary files; protect them with disk encryption and OS permissions.
+- A complete Cypher implementation or a Neo4j replacement. Unsupported clauses fail with an error rather than being ignored.
+- A graph-algorithm library. Use NetworkX or similar on exported data.
+- Built for very large graphs. The whole graph is loaded into memory when it opens; see the tested sizes in [Overview](https://graph-ted.com/graph-ted-db/docs/overview/).
+- Stable across minor versions before 1.0 (see [Versioning](#versioning)).
+- Telemetry-enabled. It makes no network calls of its own.
+
+## When to use it
+
+Good fit for prototypes, local tools, agents, and small trusted groups that want a property graph next to the app.
+
+Choose a server graph database when you need multi-tenant hosting, fine-grained remote auth, or a complete query language and enterprise feature set out of the box.
+
+## Security
+
+Data is stored as ordinary files. The library does **not** encrypt the graph folder. Security matches your environment: disk or volume encryption, OS account permissions, backups, sync tools, and whether anything listens on the network.
+
+- **Airgapped host + encrypted volume** — can be very strong; treat that environment as your boundary.
+- **Synced or shared folders** — anyone with access to the folder can read what you stored (including properties).
+- **HTTP serve** — defaults to localhost; binding beyond loopback requires an explicit host and a token. That protects the port, not the files on disk.
+
+Choose storage and network to match how sensitive the data is.
+
+## Documentation
+
+Docs: [graph-ted.com/graph-ted-db/docs](https://graph-ted.com/graph-ted-db/docs/), built from the `docs/` folder in this repository. Preview locally: see [PREVIEW.md](https://github.com/graph-ted/graph-ted-db/blob/main/PREVIEW.md).
+
+| Doc | Contents |
+|-----|----------|
+| [Overview](https://graph-ted.com/graph-ted-db/docs/overview/) | Product overview |
+| [On-disk format](https://graph-ted.com/graph-ted-db/docs/format/) | On-disk layout |
+| [openCypher subset](https://graph-ted.com/graph-ted-db/docs/cypher/) | Supported openCypher subset |
+| [Trademarks](https://graph-ted.com/graph-ted-db/docs/trademarks/) | Trademarks |
+| [HTTP](https://graph-ted.com/graph-ted-db/docs/http/) | Local HTTP serve |
+
+## Trademarks
+
+openCypher is a trademark of Neo4j, Inc. Other names are trademarks of their respective owners; no endorsement implied. See [Trademarks](https://graph-ted.com/graph-ted-db/docs/trademarks/).
+
+## Versioning
+
+Pre-1.0 (`0.1.0`). Until 1.0.0, minor versions may include breaking changes; they are noted in release notes. From 1.0.0, breaking changes bump the major version.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Feedback and issues
+
+- **Bugs, enhancement requests, docs problems:** [open an issue](https://github.com/graph-ted/graph-ted-db/issues/new/choose) using one of the forms.
+- **Questions and ideas:** [Discussions](https://github.com/graph-ted/graph-ted-db/discussions).
+- **Security vulnerabilities:** report privately as described in [SECURITY.md](https://github.com/graph-ted/graph-ted-db/blob/main/SECURITY.md), never in a public issue.
+
+Contributing: see [CONTRIBUTING.md](https://github.com/graph-ted/graph-ted-db/blob/main/CONTRIBUTING.md).
+
+## Related
+
+graph-ted-db is the local store for the graph-ted toolkit ([graph-ted.com](https://graph-ted.com/)). This repository is the database library only.

graph_ted_db-0.1.0/graph_ted_db/__init__.py

@@ -0,0 +1,23 @@
+"""Local property-graph storage for Python: open a folder and query it in-process (import graph_ted_db)."""
+
+from graph_ted_db.engine import CypherError
+from graph_ted_db.store import (
+    EdgeRecord,
+    GraphStore,
+    NodeRecord,
+    Tombstone,
+    VectorRecord,
+    init_graph,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "CypherError",
+    "EdgeRecord",
+    "GraphStore",
+    "NodeRecord",
+    "Tombstone",
+    "VectorRecord",
+    "__version__",
+    "init_graph",
+]

graph_ted_db-0.1.0/graph_ted_db/__main__.py

@@ -0,0 +1,3 @@
+from graph_ted_db.cli import main
+
+raise SystemExit(main())