context-graph-spaces 0.1.0__tar.gz

context_graph_spaces-0.1.0/.gitignore

@@ -0,0 +1,189 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+
+# VS Code
+.vscode/
+
+
+# Local agent hook configuration
+/.codex/
+/.claude/settings.local.json
+
+# Project specific files
+/enterprise-context/sic-agent/sic-scrapper/output/*
+
+# deepeval writes run caches and telemetry here; build artifacts, not source.
+.deepeval/

context_graph_spaces-0.1.0/CONTEXT.md

@@ -0,0 +1,37 @@
+# Context Graph Spaces
+
+The Enterprise edition of Context Graph: memory for many users on one shared,
+licensed Memgraph, where Memgraph's own access control enforces the isolation
+(map #501).
+
+## Language
+
+**Personal Space**:
+A member's own database, `u_<login>`, and their main database. Hooks write all of the member's activity here. Only the member and nobody else can reach it.
+_Avoid_: tenant, user database
+
+**Shared Space**:
+A database `space_<name>` that a set of members can read. Members may create and change only the labels and edge types the **Spaces Spec** allows; v1 allows curated memory only. A team or the whole org is just a Shared Space with different members.
+_Avoid_: team space (a team is one use), workspace
+
+**Spaces Spec**:
+The admin's TOML file listing members and Shared Spaces. It is the single source of desired state. `context-graph-spaces plan` diffs Memgraph against it; `apply` makes Memgraph match.
+_Avoid_: config (that's the member's own Context Graph config file)
+
+**Space Membership**:
+A `(:SpaceMembership {space, database})` node in a member's Personal Space, written by `apply`. It is how recall learns which Shared Spaces to read, because an unprivileged login can't list its own grants. Memgraph's grants remain the authority; a stale node only costs a permission error.
+
+**Service Account**:
+`cg_service`. Holds the worker role on every Shared Space and writes what members can't there, such as Chunks and entities from reconciliation.
+
+**Owned Object**:
+A database, role, user or tenant profile with a `u_`, `space_` or `cg_` prefix, or a user whose `u_<login>` database exists. The provisioner changes only owned objects.
+
+## Relationships
+
+- **Spaces Spec -> Memgraph**: `apply` creates databases, versioned roles (named by a hash of their grants), users, role assignments scoped to one database, tenant profiles and Space Memberships. Removing a member or a space revokes access; `--prune` also drops users and databases.
+- **Context Graph config -> EnterpriseSpaces**: with `edition = "enterprise"`, memgraph-context-graph's `SpaceResolver` is this package's resolver, found through the `memgraph_context_graph.editions` entry point.
+
+## Flagged ambiguities
+
+- "Role": in this package, a Memgraph auth role (`space_payments_member_3fa2c1d0`). Not a message speaker role (`actions-graph`'s `MessageRole`).

context_graph_spaces-0.1.0/LICENSE

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

context_graph_spaces-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.5
+Name: context-graph-spaces
+Version: 0.1.0
+Summary: The Enterprise edition of Context Graph: personal and shared memory spaces for many users on one Memgraph
+License: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: memgraph-context-graph>=0.5.0
+Requires-Dist: memgraph-toolbox
+Requires-Dist: neo4j>=5.0
+Requires-Dist: sessions-graph[reconciliation]>=0.6.0
+Requires-Dist: tomli>=2.0
+Provides-Extra: test
+Requires-Dist: pytest>=9.0.3; extra == 'test'
+Requires-Dist: sessions-graph[memgraph-context-graph,reconciliation]>=0.8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# context-graph-spaces
+
+The Enterprise edition of [Context Graph](../README.md): memory for many users on
+one shared, licensed Memgraph. Each user gets a **personal space**, and teams get
+**shared spaces**. Memgraph Enterprise enforces the isolation through
+multi-tenancy, role-based access control and label- and property-based access
+control. Our code doesn't filter.
+
+The Community edition (one user, one database) doesn't need this package and
+doesn't change when it's installed. A user's config file selects Enterprise
+explicitly:
+
+```toml
+edition = "enterprise"
+
+[memgraph]
+url = "bolt://memgraph.corp:7687"
+user = "ante"        # your Memgraph login is your identity
+password = "..."
+```
+
+## For admins: provisioning
+
+Spaces are declared in a spec file and applied idempotently:
+
+```toml
+members = ["ante", "bob"]
+personal_memory_limit_mb = 2048
+
+[spaces.payments]
+members = ["ante", "bob"]
+memory_limit_mb = 4096
+# labels = [...]       # what members may write; defaults to curated memory
+# edge_types = [...]
+```
+
+```bash
+export MEMGRAPH_URL=bolt://memgraph.corp:7687 MEMGRAPH_USER=<admin> MEMGRAPH_PASSWORD=...
+context-graph-spaces plan spaces.toml     # what would change
+context-graph-spaces apply spaces.toml    # make it so; prints one-time setup lines for new logins
+```
+
+What `apply` maintains:
+
+| Object | Name | Who |
+|---|---|---|
+| Personal database | `u_<login>` | its owner (main database), plus nobody else |
+| Shared database | `space_<name>` | members: read everything, write only the spec's labels |
+| Roles | `cg_u_<login>_<hash>`, `space_<name>_member_<hash>`, `cg_worker_<hash>` | named after what they grant |
+| Service login | `cg_service` | writes Chunks and entities in shared spaces |
+| Tenant profiles | `cg_<mb>mb` | memory caps from the spec |
+
+Removing someone from the spec revokes their access. Removing a space revokes
+access to it. Users and databases are only dropped with `--prune`. Only objects
+with the `u_`, `space_` and `cg_` prefixes are ever touched.
+
+## The shared-space worker
+
+Members can write only curated memory into a shared space. The derived graph
+there (chunks, entities, relations, and the embeddings recall uses) is written by
+one service login, `cg_service`. Run the worker next to `apply`, with the
+password `apply` printed once:
+
+```bash
+export CG_SERVICE_PASSWORD=...
+context-graph-spaces reconcile spaces.toml --watch     # one pass every 30s
+```
+
+Each pass, for each shared space, it does two things:
+
+1. It removes what deleted files left behind. A member's delete can't touch chunks.
+2. It reconciles changed memory files with GLiNER2 under the space's ontology.
+   No LLM is involved.
+
+Personal spaces keep reconciling locally, as in Community.
+
+## Tests
+
+The tests run end-to-end against a licensed Memgraph. The licence is read from
+`MEMGRAPH_ENTERPRISE_LICENSE` and `MEMGRAPH_ORGANIZATION_NAME` (the repo's `.env`
+locally, secrets in CI):
+
+```bash
+./scripts/dev-memgraph.sh test-enterprise
+```

context_graph_spaces-0.1.0/README.md

@@ -0,0 +1,85 @@
+# context-graph-spaces
+
+The Enterprise edition of [Context Graph](../README.md): memory for many users on
+one shared, licensed Memgraph. Each user gets a **personal space**, and teams get
+**shared spaces**. Memgraph Enterprise enforces the isolation through
+multi-tenancy, role-based access control and label- and property-based access
+control. Our code doesn't filter.
+
+The Community edition (one user, one database) doesn't need this package and
+doesn't change when it's installed. A user's config file selects Enterprise
+explicitly:
+
+```toml
+edition = "enterprise"
+
+[memgraph]
+url = "bolt://memgraph.corp:7687"
+user = "ante"        # your Memgraph login is your identity
+password = "..."
+```
+
+## For admins: provisioning
+
+Spaces are declared in a spec file and applied idempotently:
+
+```toml
+members = ["ante", "bob"]
+personal_memory_limit_mb = 2048
+
+[spaces.payments]
+members = ["ante", "bob"]
+memory_limit_mb = 4096
+# labels = [...]       # what members may write; defaults to curated memory
+# edge_types = [...]
+```
+
+```bash
+export MEMGRAPH_URL=bolt://memgraph.corp:7687 MEMGRAPH_USER=<admin> MEMGRAPH_PASSWORD=...
+context-graph-spaces plan spaces.toml     # what would change
+context-graph-spaces apply spaces.toml    # make it so; prints one-time setup lines for new logins
+```
+
+What `apply` maintains:
+
+| Object | Name | Who |
+|---|---|---|
+| Personal database | `u_<login>` | its owner (main database), plus nobody else |
+| Shared database | `space_<name>` | members: read everything, write only the spec's labels |
+| Roles | `cg_u_<login>_<hash>`, `space_<name>_member_<hash>`, `cg_worker_<hash>` | named after what they grant |
+| Service login | `cg_service` | writes Chunks and entities in shared spaces |
+| Tenant profiles | `cg_<mb>mb` | memory caps from the spec |
+
+Removing someone from the spec revokes their access. Removing a space revokes
+access to it. Users and databases are only dropped with `--prune`. Only objects
+with the `u_`, `space_` and `cg_` prefixes are ever touched.
+
+## The shared-space worker
+
+Members can write only curated memory into a shared space. The derived graph
+there (chunks, entities, relations, and the embeddings recall uses) is written by
+one service login, `cg_service`. Run the worker next to `apply`, with the
+password `apply` printed once:
+
+```bash
+export CG_SERVICE_PASSWORD=...
+context-graph-spaces reconcile spaces.toml --watch     # one pass every 30s
+```
+
+Each pass, for each shared space, it does two things:
+
+1. It removes what deleted files left behind. A member's delete can't touch chunks.
+2. It reconciles changed memory files with GLiNER2 under the space's ontology.
+   No LLM is involved.
+
+Personal spaces keep reconciling locally, as in Community.
+
+## Tests
+
+The tests run end-to-end against a licensed Memgraph. The licence is read from
+`MEMGRAPH_ENTERPRISE_LICENSE` and `MEMGRAPH_ORGANIZATION_NAME` (the repo's `.env`
+locally, secrets in CI):
+
+```bash
+./scripts/dev-memgraph.sh test-enterprise
+```

context_graph_spaces-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "context-graph-spaces"
+version = "0.1.0"
+description = "The Enterprise edition of Context Graph: personal and shared memory spaces for many users on one Memgraph"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+classifiers = [
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "memgraph-context-graph>=0.5.0",
+    "memgraph-toolbox",
+    # Shared spaces hold sessions-graph's memory files: apply sets up its schema there, and the
+    # worker reconciles them (the reconciliation extra brings unstructured2graph).
+    "sessions-graph[reconciliation]>=0.6.0",
+    "neo4j>=5.0",
+    # tomllib on 3.11+; tomli for 3.10, which ty checks against.
+    "tomli>=2.0",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=9.0.3",
+    "sessions-graph[memgraph-context-graph,reconciliation]>=0.8.0",
+]
+
+[project.scripts]
+context-graph-spaces = "context_graph_spaces.cli:main"
+
+[project.entry-points."memgraph_context_graph.editions"]
+enterprise = "context_graph_spaces.resolver:EnterpriseSpaces"
+
+[tool.uv.sources]
+memgraph-context-graph = { workspace = true }
+memgraph-toolbox = { workspace = true }
+sessions-graph = { workspace = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

context_graph_spaces-0.1.0/src/context_graph_spaces/__init__.py

@@ -0,0 +1,13 @@
+"""Context Graph's Enterprise edition: personal and shared memory spaces for many users on one Memgraph.
+
+Selected by ``edition = "enterprise"`` in the Context Graph config file, which
+makes :class:`EnterpriseSpaces` the space resolver. The admin side provisions
+spaces from a spec (:mod:`.spec`, :mod:`.provision`, ``context-graph-spaces
+plan|apply``).
+"""
+
+from .provision import Applied, Plan, apply, observed_state, plan
+from .resolver import EnterpriseSpaces
+from .spec import Spec, SpecError, load_spec
+
+__all__ = ["Applied", "EnterpriseSpaces", "Plan", "Spec", "SpecError", "apply", "load_spec", "observed_state", "plan"]

context_graph_spaces-0.1.0/src/context_graph_spaces/cli.py

@@ -0,0 +1,123 @@
+"""``context-graph-spaces``: the admin's commands for provisioning spaces from a spec.
+
+The admin connection comes from flags, falling back to ``MEMGRAPH_URL`` /
+``MEMGRAPH_USER`` / ``MEMGRAPH_PASSWORD``. This is an interactive admin tool,
+not a hook, so the config-file-only rule for hooks doesn't apply; the admin's
+login is never written anywhere.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from typing import TYPE_CHECKING, Any, cast
+
+from .provision import SERVICE_ACCOUNT, Plan, Query, Step, apply, observed_state, plan
+from .spec import SpecError, load_spec
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from .spec import Spec
+
+#: Where the reconcile worker finds the service login's password.
+SERVICE_PASSWORD_ENV = "CG_SERVICE_PASSWORD"
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run ``plan`` or ``apply``; returns the process exit code."""
+    parser = argparse.ArgumentParser(prog="context-graph-spaces", description=__doc__)
+    parser.add_argument("--url", default=os.environ.get("MEMGRAPH_URL", "bolt://localhost:7687"))
+    parser.add_argument("--user", default=os.environ.get("MEMGRAPH_USER", ""), help="An admin login.")
+    parser.add_argument("--password", default=os.environ.get("MEMGRAPH_PASSWORD", ""))
+    commands = parser.add_subparsers(dest="command", required=True)
+    for name, text in (("plan", "Show what apply would change."), ("apply", "Make Memgraph match the spec.")):
+        command = commands.add_parser(name, help=text)
+        command.add_argument("spec", help="The spaces spec (TOML).")
+        command.add_argument("--prune", action="store_true", help="Also drop removed users and databases.")
+    reconcile = commands.add_parser("reconcile", help="Reconcile shared spaces' changed memory files, as cg_service.")
+    reconcile.add_argument("spec", help="The spaces spec (TOML): which shared spaces to reconcile.")
+    reconcile.add_argument("--watch", action="store_true", help="Keep going, one pass every --interval seconds.")
+    reconcile.add_argument("--interval", type=float, default=30.0)
+    args = parser.parse_args(argv)
+
+    try:
+        spec = load_spec(args.spec)
+    except SpecError as exc:
+        print(exc, file=sys.stderr)
+        return 2
+    if args.command == "reconcile":
+        return _reconcile(spec, args.url, watch=args.watch, interval=args.interval)
+    query, close = admin_query(args.url, args.user, args.password)
+    try:
+        if args.command == "plan":
+            _print_plan(plan(spec, observed_state(query, spec.members), prune=args.prune))
+            return 0
+        applied = apply(spec, query, prune=args.prune)
+    finally:
+        close()
+    _print_steps(applied.steps, "Applied" if applied.steps else "Nothing to change; Memgraph matches the spec.")
+    _print_kept(applied.kept)
+    for login, password in sorted(applied.passwords.items()):
+        if login == SERVICE_ACCOUNT:
+            print(f"\nNew service login {login!r} for the shared-space reconcile worker; it isn't stored anywhere.")
+            print(f"  Give the worker: {SERVICE_PASSWORD_ENV}='{password}'")
+            continue
+        print(f"\nNew login {login!r}. Hand this to them once; it isn't stored anywhere:")
+        print(f"  memgraph-context-graph join {args.url} {login} --password='{password}'")
+    return 0
+
+
+def _reconcile(spec: Spec, url: str, *, watch: bool, interval: float) -> int:
+    """Run the worker once, or every *interval* seconds with *watch*; exit 1 if the last pass had an error."""
+    import time
+
+    from .worker import reconcile_spaces
+
+    password = os.environ.get(SERVICE_PASSWORD_ENV)
+    if not password:
+        print(f"Set {SERVICE_PASSWORD_ENV} to {SERVICE_ACCOUNT}'s password (apply printed it once).", file=sys.stderr)
+        return 2
+    while True:
+        reports = reconcile_spaces(spec, url=url, password=password)
+        for report in reports:
+            if report.error:
+                print(f"{report.space}: not reconciled: {report.error}", file=sys.stderr)
+                continue
+            failed = "".join(f"\n  failed {path}: {error}" for path, error in report.failed)
+            print(f"{report.space}: {len(report.completed)} reconciled, {report.pruned} leftovers removed{failed}")
+        if not watch:
+            return 1 if any(report.error or report.failed for report in reports) else 0
+        time.sleep(interval)
+
+
+def admin_query(url: str, user: str, password: str) -> tuple[Query, Any]:
+    """A :data:`~.provision.Query` over one admin driver, and the function that closes it."""
+    import neo4j
+
+    driver = neo4j.GraphDatabase.driver(url, auth=(user, password))
+
+    def query(statement: str, database: str | None, params: dict[str, Any] | None) -> list[dict[str, Any]]:
+        # Auth and multi-database DDL can't run in an explicit transaction, so each statement gets its own session.
+        with driver.session(database=database) as session:
+            # The driver's stubs want a LiteralString; admin DDL is built from names spec._NAME has validated.
+            return [record.data() for record in session.run(cast("Any", statement), params or {})]
+
+    return query, driver.close
+
+
+def _print_plan(the_plan: Plan) -> None:
+    _print_steps(the_plan.steps, "Plan:" if the_plan.steps else "Nothing to change; Memgraph matches the spec.")
+    _print_kept(the_plan.kept)
+
+
+def _print_steps(steps: list[Step], heading: str) -> None:
+    print(heading)
+    for step in steps:
+        print(f"  + {step.summary}")
+
+
+def _print_kept(kept: list[str]) -> None:
+    if kept:
+        print(f"Kept (pass --prune to drop): {', '.join(kept)}")