saengra 0.1.0__tar.gz

saengra-0.1.0/CMakeLists.txt

@@ -0,0 +1,46 @@
+cmake_minimum_required(VERSION 3.15)
+project(saengra VERSION 0.1.0 LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+# Find Python
+find_package(Python COMPONENTS Interpreter Development REQUIRED)
+
+# Build saengra_core from saengra-server
+add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/saengra-server ${CMAKE_CURRENT_BINARY_DIR}/saengra-server-build)
+
+# Create the Python extension module
+Python_add_library(c_extension MODULE
+    src/adapter.cpp
+)
+
+target_link_libraries(c_extension PRIVATE
+    saengra_core
+    ${Python_LIBRARIES}
+)
+
+target_include_directories(c_extension PRIVATE
+    ${Python_INCLUDE_DIRS}
+)
+
+# Set output name and location
+set_target_properties(c_extension PROPERTIES
+    PREFIX ""
+    OUTPUT_NAME "c_extension"
+)
+
+if(DEFINED CMAKE_LIBRARY_OUTPUT_DIRECTORY)
+    set_target_properties(c_extension PROPERTIES
+        LIBRARY_OUTPUT_DIRECTORY "${CMAKE_LIBRARY_OUTPUT_DIRECTORY}"
+    )
+else()
+    set_target_properties(c_extension PROPERTIES
+        LIBRARY_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/saengra"
+    )
+endif()
+
+install(TARGETS c_extension
+    LIBRARY DESTINATION saengra
+)

saengra-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tigran Saluev
+
+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.

saengra-0.1.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include CMakeLists.txt
+include src/*.cpp
+recursive-include saengra-server *.cmake *.cpp *.h *.hpp *.proto *.l *.y
+include saengra-server/CMakeLists.txt
+recursive-include saengra-server/src *
+recursive-include saengra-server/include *
+recursive-include saengra-server/parser *
+recursive-include saengra-server/proto *

saengra-0.1.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: saengra
+Version: 0.1.0
+Summary: Reactive graph database with pattern matching
+Author-email: Tigran Saluev <tigran@saluev.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Saluev/saengra
+Project-URL: Repository, https://github.com/Saluev/saengra
+Project-URL: Issues, https://github.com/Saluev/saengra/issues
+Keywords: graph,database,reactive,pattern-matching,entity
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: C++
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: frozendict>=2.4.6
+Requires-Dist: protobuf>=4.0
+Requires-Dist: termcolor>=2.4.0
+Provides-Extra: socket
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: cibuildwheel; extra == "dev"
+Dynamic: license-file
+
+# Saengra
+
+Python wrapper for Saengra graph database.
+
+## Quickstart: primitives and edges
+
+Saengra is a graph database. It supports hashable Python objects (**primitives**) as graph
+vertices. Built-in types like `int` or `str` can be used directly; also Saengra provides `@primitive`
+decorator to declare dataclass-like types to be used as graph vertices.
+
+Directed edges between primitives are always labelled with a string (**edge label**). It can
+be an arbitrary string, but the engine is optimized to support limited number of different labels per graph.
+There can't be two edges between the same two primitives with the same label.
+
+We can construct a graph directly from primitives and edges by using elementary graph operations: 
+
+```python
+from datetime import datetime
+from saengra import primitive, Environment
+from saengra.graph import AddVertex, AddEdge
+
+@primitive
+class user:
+    id: int
+
+u1 = user(id=1)
+u2 = user(id=2)
+u1_registered_at = datetime(2022, 1, 1, 12, 0, 0)
+u2_registered_at = datetime(2023, 2, 3, 15, 0, 0)
+
+env = Environment()
+env.update(
+    AddVertex(u1),
+    AddVertex(u2),
+    AddVertex(u1_registered_at),
+    AddVertex(u2_registered_at),
+    AddEdge(u1, "follows", u2),
+    AddEdge(u1, "registered_at", u1_registered_at),
+    AddEdge(u2, "registered_at", u2_registered_at),
+)
+env.commit()
+```
+
+## Quickstart: entities and environment
+
+Operating with vertices and edges is tedious and slow. A higher-level abstraction, **entities**,
+is provided to make working with graph more like your normal object-oriented programming.
+
+Let's declare some entity classes and rewrite the code above:
+
+```python
+from datetime import datetime
+from saengra import primitive, Entity, Environment
+
+@primitive
+class user:
+    id: int
+
+class User(Entity, user):
+    registered_at: datetime
+    follows: set["User"]
+
+env = Environment(entity_types=[User])
+
+u1 = User.create(env, id=1, registered_at=datetime(2022, 1, 1, 12, 0, 0))
+u2 = User.create(env, id=2, registered_at=datetime(2023, 2, 3, 15, 0, 0))
+u1.follows.add(u2)
+
+env.commit()
+```
+
+## Quickstart: expressions and observers
+
+Saengra introduces a domain-specific language to describe subgraphs of the graph, i.e. subset of
+vertices and edges. These expressions are quite similar to queries in SQL.
+
+```python
+# Find all subscriptions, i.e. pairs (u1, u2) where u1 follows u2:
+env.match("user as u1 -follows> user as u2")
+# -> [{"u1": User(id=1), "u2": User(id=2)}]
+
+# Find all mutual subscriptions:
+env.match("user as u1 <follows> user as u2")
+# -> []
+```
+
+But the most powerful aspect of Saengra is its observation capability. Saengra can match
+expressions incrementally after processing graph updates, and notify the program about created,
+changed and deleted subgraphs after each commit.
+
+```python
+from saengra import observer
+
+mutual_follow = observer("user as u1 <follows> user as u2")
+
+
+@mutual_follow.on_create
+def notify_mutuals(u1: User, u2: User):
+    print(f"{u1} is now mutuals with {u2}!")
+
+
+env.register_observers([mutual_follow])
+
+u2.follows.add(u1)
+env.commit()
+# -> User(id=1) is now mutuals with User(id=2)!
+# -> User(id=2) is now mutuals with User(id=1)!
+```
+
+## Generating Protobuf Code
+
+The `messages_pb2.py` file is generated from the protobuf definitions in `saengra-server/proto/messages.proto`.
+
+To regenerate:
+
+```bash
+protoc --python_out=saengra --proto_path=saengra-server/proto saengra-server/proto/messages.proto
+```
+
+Requirements:
+- `protoc` (Protocol Buffers compiler) must be installed
+- Python protobuf library: `pip install protobuf>=4.21.0`
+
+## Usage
+
+### Option 1: Automatically start server
+
+```python
+from saengra.client import SaengraClient
+
+# Client automatically starts saengra-server in background
+with SaengraClient() as client:
+    # Connect to a graph
+    created = client.connect("my_graph")
+
+    # Add vertices and edges
+    client.apply_updates([
+        # Your updates here
+    ])
+
+    # Commit changes
+    response = client.commit()
+```
+
+The client expects `saengra-server` binary to be available in PATH.
+
+### Option 2: Connect to existing server
+
+```python
+from saengra.client import SaengraClient
+
+# Connect to an existing server socket
+with SaengraClient(socket_path="/path/to/server.sock") as client:
+    # Connect to a graph
+    created = client.connect("my_graph")
+
+    # Work with the graph...
+```
+
+When using an existing socket, the client will not start or stop the server process, and will not clean up the socket file.

saengra-0.1.0/pyproject.toml

@@ -0,0 +1,96 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel", "cmake>=3.15"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "saengra"
+version = "0.1.0"
+description = "Reactive graph database with pattern matching"
+readme = "saengra/README.md"
+license = {text = "MIT"}
+authors = [
+    {name = "Tigran Saluev", email = "tigran@saluev.com"}
+]
+keywords = ["graph", "database", "reactive", "pattern-matching", "entity"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: C++",
+    "Topic :: Database",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "frozendict>=2.4.6",
+    "protobuf>=4.0",
+    "termcolor>=2.4.0"
+]
+
+[project.optional-dependencies]
+socket = []  # TODO move protobuf dep here, make optional
+dev = [
+    "pytest>=7.0",
+    "pytest-cov",
+    "build",
+    "twine",
+    "cibuildwheel",
+]
+
+[project.urls]
+Homepage = "https://github.com/Saluev/saengra"
+Repository = "https://github.com/Saluev/saengra"
+Issues = "https://github.com/Saluev/saengra/issues"
+
+[tool.setuptools]
+packages = ["saengra", "saengra.utilities"]
+package-dir = {"" = "."}
+
+[tool.setuptools.package-data]
+saengra = ["*.so", "*.pyd", "*.dylib"]
+
+# cibuildwheel configuration for multi-platform builds
+[tool.cibuildwheel]
+# Build for these Python versions
+build = "cp310-* cp311-* cp312-*"
+# Skip 32-bit builds and musllinux (alpine)
+skip = "*-win32 *-manylinux_i686 *-musllinux_*"
+
+[tool.cibuildwheel.linux]
+# Install build dependencies before building
+before-all = """
+    yum install -y build-essential make cmake git protobuf-devel boost-devel spdlog-devel bison flex || \
+    apt-get update && apt-get install -y --no-install-recommends build-essential make cmake git libprotobuf-dev protobuf-compiler libboost-dev libspdlog-dev bison flex
+"""
+# Build and install abseil from source
+before-build = """
+    git clone --depth 1 --branch 20240116.2 https://github.com/abseil/abseil-cpp.git /tmp/abseil \
+        && cd /tmp/abseil \
+        && cmake -S . -B build \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DCMAKE_POSITION_INDEPENDENT_CODE=ON \
+            -DABSL_ENABLE_INSTALL=ON \
+            -DABSL_USE_SYSTEM_INCLUDES=ON \
+        && cmake --build build -j4 \
+        && cmake --install build \
+        && rm -rf /tmp/abseil
+"""
+
+[tool.cibuildwheel.macos]
+# Use Homebrew for dependencies
+before-all = "brew install cmake protobuf boost spdlog abseil bison flex"
+environment = { MACOSX_DEPLOYMENT_TARGET = "10.15" }
+# Build for both Intel and ARM
+archs = ["x86_64", "arm64"]
+
+[tool.cibuildwheel.windows]
+# Windows builds require vcpkg or pre-installed dependencies
+before-all = """
+    choco install cmake git -y
+"""
+# Note: Windows builds are more complex due to dependencies
+# Consider using vcpkg for abseil, protobuf, etc.

saengra-0.1.0/saengra/README.md

@@ -0,0 +1,160 @@
+# Saengra
+
+Python wrapper for Saengra graph database.
+
+## Quickstart: primitives and edges
+
+Saengra is a graph database. It supports hashable Python objects (**primitives**) as graph
+vertices. Built-in types like `int` or `str` can be used directly; also Saengra provides `@primitive`
+decorator to declare dataclass-like types to be used as graph vertices.
+
+Directed edges between primitives are always labelled with a string (**edge label**). It can
+be an arbitrary string, but the engine is optimized to support limited number of different labels per graph.
+There can't be two edges between the same two primitives with the same label.
+
+We can construct a graph directly from primitives and edges by using elementary graph operations: 
+
+```python
+from datetime import datetime
+from saengra import primitive, Environment
+from saengra.graph import AddVertex, AddEdge
+
+@primitive
+class user:
+    id: int
+
+u1 = user(id=1)
+u2 = user(id=2)
+u1_registered_at = datetime(2022, 1, 1, 12, 0, 0)
+u2_registered_at = datetime(2023, 2, 3, 15, 0, 0)
+
+env = Environment()
+env.update(
+    AddVertex(u1),
+    AddVertex(u2),
+    AddVertex(u1_registered_at),
+    AddVertex(u2_registered_at),
+    AddEdge(u1, "follows", u2),
+    AddEdge(u1, "registered_at", u1_registered_at),
+    AddEdge(u2, "registered_at", u2_registered_at),
+)
+env.commit()
+```
+
+## Quickstart: entities and environment
+
+Operating with vertices and edges is tedious and slow. A higher-level abstraction, **entities**,
+is provided to make working with graph more like your normal object-oriented programming.
+
+Let's declare some entity classes and rewrite the code above:
+
+```python
+from datetime import datetime
+from saengra import primitive, Entity, Environment
+
+@primitive
+class user:
+    id: int
+
+class User(Entity, user):
+    registered_at: datetime
+    follows: set["User"]
+
+env = Environment(entity_types=[User])
+
+u1 = User.create(env, id=1, registered_at=datetime(2022, 1, 1, 12, 0, 0))
+u2 = User.create(env, id=2, registered_at=datetime(2023, 2, 3, 15, 0, 0))
+u1.follows.add(u2)
+
+env.commit()
+```
+
+## Quickstart: expressions and observers
+
+Saengra introduces a domain-specific language to describe subgraphs of the graph, i.e. subset of
+vertices and edges. These expressions are quite similar to queries in SQL.
+
+```python
+# Find all subscriptions, i.e. pairs (u1, u2) where u1 follows u2:
+env.match("user as u1 -follows> user as u2")
+# -> [{"u1": User(id=1), "u2": User(id=2)}]
+
+# Find all mutual subscriptions:
+env.match("user as u1 <follows> user as u2")
+# -> []
+```
+
+But the most powerful aspect of Saengra is its observation capability. Saengra can match
+expressions incrementally after processing graph updates, and notify the program about created,
+changed and deleted subgraphs after each commit.
+
+```python
+from saengra import observer
+
+mutual_follow = observer("user as u1 <follows> user as u2")
+
+
+@mutual_follow.on_create
+def notify_mutuals(u1: User, u2: User):
+    print(f"{u1} is now mutuals with {u2}!")
+
+
+env.register_observers([mutual_follow])
+
+u2.follows.add(u1)
+env.commit()
+# -> User(id=1) is now mutuals with User(id=2)!
+# -> User(id=2) is now mutuals with User(id=1)!
+```
+
+## Generating Protobuf Code
+
+The `messages_pb2.py` file is generated from the protobuf definitions in `saengra-server/proto/messages.proto`.
+
+To regenerate:
+
+```bash
+protoc --python_out=saengra --proto_path=saengra-server/proto saengra-server/proto/messages.proto
+```
+
+Requirements:
+- `protoc` (Protocol Buffers compiler) must be installed
+- Python protobuf library: `pip install protobuf>=4.21.0`
+
+## Usage
+
+### Option 1: Automatically start server
+
+```python
+from saengra.client import SaengraClient
+
+# Client automatically starts saengra-server in background
+with SaengraClient() as client:
+    # Connect to a graph
+    created = client.connect("my_graph")
+
+    # Add vertices and edges
+    client.apply_updates([
+        # Your updates here
+    ])
+
+    # Commit changes
+    response = client.commit()
+```
+
+The client expects `saengra-server` binary to be available in PATH.
+
+### Option 2: Connect to existing server
+
+```python
+from saengra.client import SaengraClient
+
+# Connect to an existing server socket
+with SaengraClient(socket_path="/path/to/server.sock") as client:
+    # Connect to a graph
+    created = client.connect("my_graph")
+
+    # Work with the graph...
+```
+
+When using an existing socket, the client will not start or stop the server process, and will not clean up the socket file.

saengra-0.1.0/saengra/__init__.py

@@ -0,0 +1,10 @@
+"""Saengra Python client library."""
+
+__version__ = "0.1.0"
+
+from saengra.c_extension import DirectAdapter
+from saengra.entity import primitive, Entity
+from saengra.environment import Environment
+from saengra.factory import EntityFactory
+from saengra.observer import observer
+from saengra.socket_adapter import SocketAdapter

saengra-0.1.0/saengra/adapter.py

@@ -0,0 +1,37 @@
+from typing import Iterable, Protocol, TypeAlias
+
+from saengra.api import Observation, Observer
+from saengra.graph import Update, Primitive, Edge, Subgraph
+
+ShouldCommitAgain: TypeAlias = bool
+
+
+class Adapter(Protocol):
+    """Protocol for adapters that communicate with the saengra graph engine."""
+
+    def update(
+        self, update_or_updates: Update | list[Update] | tuple[Update, ...]
+    ) -> None: ...
+
+    def flush(self) -> None: ...
+
+    def commit(self) -> tuple[ShouldCommitAgain, list[Observation]]: ...
+
+    def rollback(self) -> None: ...
+
+    def find_vertices(self, *, with_type_name: str | None = None) -> list[Primitive]: ...
+
+    def find_edges(
+        self,
+        *,
+        with_label: str | None = None,
+        from_vertices: list[Primitive] | tuple[Primitive, ...] | None = None,
+        to_vertices: list[Primitive] | tuple[Primitive, ...] | None = None,
+    ) -> list[Edge]: ...
+
+    def find_all(self) -> tuple[list[Primitive], list[Edge]]: ...
+
+    def observe(self, observers: Iterable[Observer]) -> None: ...
+
+    def match(self, expression: str, *placeholder_values: Primitive) -> list[Subgraph]: ...
+

saengra-0.1.0/saengra/api.py

@@ -0,0 +1,50 @@
+from dataclasses import dataclass, field
+from enum import Enum
+
+from saengra import messages_pb2
+from saengra.graph import Primitive, Edge, Subgraph
+
+
+@dataclass(frozen=True)
+class Observer:
+    id: str
+    expression: str
+    placeholder_values: tuple[Primitive, ...] = field(default_factory=tuple)
+    on_create: bool = False
+    on_change: bool = False
+    on_delete: bool = False
+
+
+class ObservationType(Enum):
+    ON_CREATE = messages_pb2.CommitResponse.Observation.ON_CREATE
+    ON_CHANGE = messages_pb2.CommitResponse.Observation.ON_CHANGE
+    ON_DELETE = messages_pb2.CommitResponse.Observation.ON_DELETE
+
+
+@dataclass(frozen=True)
+class Observation:
+    observer_id: str
+    type: ObservationType
+    variables: dict[str, Primitive]
+
+
+class CommitStatus(Enum):
+    OK = messages_pb2.CommitResponse.OK
+    REQUIRES_REPEATED_COMMIT = messages_pb2.CommitResponse.REQUIRES_REPEATED_COMMIT
+
+
+@dataclass(frozen=True)
+class CommitResponse:
+    status: CommitStatus
+    observations: list[Observation]
+
+
+@dataclass(frozen=True)
+class FindResponse:
+    vertices: list[Primitive]
+    edges: list[Edge]
+
+
+@dataclass(frozen=True)
+class MatchResponse:
+    subgraphs: list[Subgraph]