pycontextdb 0.3.0__tar.gz → 0.3.2__tar.gz

pycontextdb-0.3.2/.github/pull_request_template.md

@@ -0,0 +1,28 @@
+## Summary
+
+<!-- What changed, and why. Evals win over prose. -->
+
+## Open-core classification
+
+Select exactly one and justify placement against `OPEN_CORE.md`.
+
+- [ ] No capability change — docs/tests/build/maintenance only.
+- [ ] Semantic — portable offline correctness.
+- [ ] Contract — interface/schema/protocol.
+- [ ] Reference — minimal single-node implementation.
+- [ ] Operated — multi-tenant/process/region/people/SLA coordination; this PR
+      does not belong in the public SDK.
+
+**Why this repository is the correct side of the boundary:**
+
+<!-- For mixed features, identify the open contract and private implementation. -->
+
+## Checklist
+
+- [ ] `pytest tests/evals/ -v` passes, or I explain why not.
+- [ ] `python scripts/check_open_core_boundary.py` passes.
+- [ ] `contextdb.init`, `factual.add`, `factual.recall`, and `search` keep working; new fields have backward-compatible defaults.
+- [ ] No new runtime dependency without a discussion first.
+- [ ] No hosted auth, entitlements, billing, control-plane, enterprise,
+      deployment, migration-orchestration, or fleet code entered the SDK.
+- [ ] Substantial contribution: I agree to the CLA in CONTRIBUTING.md (legal name and email in this description). Trivial typo PRs may skip this.

{pycontextdb-0.3.0 → pycontextdb-0.3.2}/.github/workflows/ci.yml

@@ -54,6 +54,12 @@ jobs:
           python -m pip install --upgrade pip
           pip install -e ".[dev]"
 
+      - name: Open-core boundary
+        run: python scripts/check_open_core_boundary.py
+        env:
+          CONTEXTDB_REQUIRE_PR_CLASSIFICATION: ${{ github.event_name == 'pull_request' }}
+          CONTEXTDB_PR_BODY: ${{ github.event.pull_request.body }}
+
       - name: Lint with ruff
         run: ruff check .
 
@@ -62,3 +68,42 @@ jobs:
 
       - name: Run tests
         run: pytest
+
+  postgres:
+    name: Postgres integration
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    env:
+      CONTEXTDB_TEST_POSTGRES_URL: postgresql://postgres:postgres@127.0.0.1:5432/postgres
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install package with Postgres support
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,postgres]"
+
+      - name: Run real Postgres tests
+        run: |
+          pytest \
+            tests/unit/test_postgres_concurrency.py \
+            tests/unit/test_scoped_id_access.py \
+            tests/unit/test_vector_scope.py

{pycontextdb-0.3.0 → pycontextdb-0.3.2}/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 ## Unreleased
 
+## 0.3.2 — 2026-08-20
+
+### Added
+
+- Host-owned asyncpg pools and embedding providers can be shared safely across
+  project runtimes without being closed on runtime eviction.
+- Mutations return project-scoped memory versions and Postgres WAL positions;
+  reads can require those floors and fail closed when unavailable.
+- Embeddings carry model identity and distinct query/document roles, including
+  role-aware OpenAI-compatible transport.
+- Project-scoped vector and immutable item caches remove redundant warm recall
+  queries while preserving user isolation and cross-worker coherence.
+- A durable read-audit hook lets hosted runtimes persist exact PII-processed
+  recall evidence outside the synchronous SDK audit chain.
+- The open-core constitution, PR classification, CI source scanner, and release
+  gate prevent operated Cloud capabilities from entering the Apache package.
+
+### Fixed
+
+- Memory mutation, project/global revision changes, and write audit now commit
+  in one Postgres transaction.
+- Advisory locks execute their protected work on the same transaction-bound
+  connection instead of accidentally hopping pool connections.
+- Public commercial-use guidance now matches Apache-2.0 while preserving
+  ContextDB trademark controls.
+
+`contextdb.init`, `factual.add`, `factual.recall`, and `search` remain
+backward-compatible. All new host-sharing and consistency arguments are
+optional.
+
+## 0.3.1 — 2026-08-18
+
+### Fixed
+
+- README links to docs/COMMERCIAL.md/CONTRIBUTING.md are absolute GitHub
+  URLs — relative targets 404 on the PyPI project page.
+- `scripts/check_release.py` now scans the built package description for
+  relative Markdown links so this fails in CI before it reaches PyPI.
+
 ## 0.3.0 — 2026-08-18
 
 Host API scope hardening:

{pycontextdb-0.3.0 → pycontextdb-0.3.2}/COMMERCIAL.md

@@ -26,9 +26,13 @@ You may not, without a commercial agreement with Atoms AI:
 
 ## Resale and commercial agreements
 
-If your company resells ContextDB as a service or as part of a service,
-or wants OEM/embedded licensing, support, or a trademark arrangement,
-contact **contextdb@atomsai.com** before you ship.
+Apache-2.0 permits commercial use, modification, redistribution, embedding,
+and hosted use of the code, subject to its terms. No separate copyright
+license is required for those uses.
+
+If your company wants to use the ContextDB name or logo for a hosted offering,
+or wants a supported OEM arrangement, Cloud service, support, or a trademark
+agreement, contact **contextdb@atomsai.com**.
 
 ## Attribution (optional)
 

{pycontextdb-0.3.0 → pycontextdb-0.3.2}/CONTRIBUTING.md

@@ -7,7 +7,10 @@ gates.
 ## What we accept here
 
 Trust and safety correctness, local runtime fixes, adapters, docs, and
-evals. Evals win over prose: `pytest tests/evals/ -v`.
+evals. Portable contracts and minimal single-node reference implementations
+also belong here. Classify every substantial change under
+[OPEN_CORE.md](OPEN_CORE.md). Evals win over prose:
+`pytest tests/evals/ -v`.
 
 We do **not** accept:
 
@@ -15,6 +18,9 @@ We do **not** accept:
   no flags that only work against a hosted service
 - Imports of packages outside the declared dependencies
 - Changes that loosen PII-before-embed or the hash-chained audit log
+- Hosted auth, tenancy, entitlements, billing, organization control-plane,
+  enterprise governance, managed-service, deployment, migration-orchestration,
+  or fleet code
 
 ## Contributor License Agreement
 

pycontextdb-0.3.2/OPEN_CORE.md

@@ -0,0 +1,80 @@
+# ContextDB open-core constitution
+
+**Status: binding for all future work.** Changes require an explicit
+architecture decision and maintainer approval.
+
+> Open the single-node semantics and reference engine. Keep multi-tenant coordination, operated guarantees, governance, and proof private.
+
+This repository is the public Apache-2.0 engine. It must remain complete,
+useful offline, inspectable, and safe without a hosted account, license key,
+paid flag, time bomb, or phone-home.
+
+Existing Apache grants are permanent. New code is reviewed prospectively
+against this constitution before merge and again before package publication.
+
+## Four change classes
+
+Every capability-changing contribution is classified as exactly one:
+
+1. **Semantic** — portable correctness required offline: open implementation.
+2. **Contract** — interface, schema, protocol, or compatibility test: open.
+3. **Reference** — minimal single-node implementation proving a contract: open.
+4. **Operated** — coordinates tenants, processes, regions, people, or an SLA:
+   private Cloud implementation, not this repository.
+
+Docs, tests, and maintenance with no capability change declare that explicitly.
+Mixed features are split. This repository may contain the contract and minimal
+reference implementation. Distributed schedulers, controllers, managed
+workers, deployment topology, and operations stay private.
+
+## What belongs here
+
+- Memory and epistemic data models.
+- `TrustPolicy`, act/ask/abstain, confirmation, and local explanation.
+- PII-before-embed, injection defenses, and public adversarial evals.
+- Local CRUD, SQLite, and a basic Postgres reference adapter.
+- Atomic mutation/version/audit behavior required for correct storage.
+- Deletion semantics and local verification.
+- Portable consistency-token, embedding-provider, and connector contracts.
+- Minimal reference implementations and compatibility tests.
+
+Safety and correctness are never commercially gated or intentionally weaker
+than the hosted service.
+
+## What does not belong here
+
+- Hosted gateway, tenancy, API-key auth, entitlements, quotas, billing, or
+  abuse controls.
+- Organization/project/team control plane or governance console.
+- Multi-worker routing, replica orchestration, failover, autoscaling, backups,
+  incidents, or availability guarantees.
+- Managed model fleet, batching service, backfill control, or deployment code.
+- Managed connector sync, checkpoints, retries, observability, or support SLAs.
+- Organization Action Ledger, signed compliance exports, or retention service.
+- Policy rollout/canary/approval controllers.
+- SSO, SCIM, KMS/BYOK, private networking, residency, or contractual controls.
+
+Thin generated Cloud clients, public API schemas, connector interfaces, and
+common community adapters are public distribution artifacts because they grow
+the ecosystem; they may live in separate public packages and contain no hosted
+implementation.
+
+## Contribution and release gate
+
+- Pull requests declare one change class and justify repository placement.
+- Ambiguous changes stop for boundary review; publication is never the default.
+- Contract tests may be shared; private implementations are not copied here.
+- Every PyPI release receives an open-core diff review.
+- `scripts/check_open_core_boundary.py` and CI enforce mechanical invariants.
+
+Private code can be opened later. An Apache grant cannot be clawed back.
+
+## Commercial model
+
+ContextDB Cloud sells operation, coordination, governance, and proof of this
+open correctness model. The SDK is not a crippled free tier. If Cloud cannot
+win while this engine is useful, Cloud must become stronger rather than making
+the SDK weaker.
+
+See [COMMERCIAL.md](COMMERCIAL.md) for trademark rules. Apache-2.0 permits
+commercial use of the code; it does not grant rights to ContextDB trademarks.

{pycontextdb-0.3.0 → pycontextdb-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pycontextdb
-Version: 0.3.0
+Version: 0.3.2
 Summary: The unified context layer for AI agents — memory you can act on without treating wishes as facts
 Project-URL: Homepage, https://github.com/atomsai/contextdb
 Project-URL: Documentation, https://contextdb.dev
@@ -618,8 +618,8 @@ pip install 'pycontextdb[postgres]'
 db = contextdb.init(storage_url="postgresql://...")
 ```
 
-See [docs/serve.md](docs/serve.md), [docs/multi_tenant.md](docs/multi_tenant.md),
-and [docs/trust_policy.md](docs/trust_policy.md).
+See [docs/serve.md](https://github.com/atomsai/contextdb/blob/main/docs/serve.md), [docs/multi_tenant.md](https://github.com/atomsai/contextdb/blob/main/docs/multi_tenant.md),
+and [docs/trust_policy.md](https://github.com/atomsai/contextdb/blob/main/docs/trust_policy.md).
 
 ## License and attribution
 
@@ -628,14 +628,16 @@ this README ships in this tree, with no feature gates. **ContextDB** is a
 trademark; the Apache license is not a trademark license. Reselling
 ContextDB as a service, or as part of one, under the ContextDB name or
 branding requires a commercial agreement with Atoms AI — contact
-contextdb@atomsai.com (see [COMMERCIAL.md](COMMERCIAL.md)). A public
+contextdb@atomsai.com (see [COMMERCIAL.md](https://github.com/atomsai/contextdb/blob/main/COMMERCIAL.md)).
+The binding product boundary is documented in
+[OPEN_CORE.md](https://github.com/atomsai/contextdb/blob/main/OPEN_CORE.md). A public
 credit line is optional — if you want one, use **Built with ContextDB**
 linking to this repository.
 
 ## Contributing
 
 Apache 2.0 — see [LICENSE](https://github.com/atomsai/contextdb/blob/main/LICENSE).
-Substantial PRs need a CLA ([CONTRIBUTING.md](CONTRIBUTING.md)).
+Substantial PRs need a CLA ([CONTRIBUTING.md](https://github.com/atomsai/contextdb/blob/main/CONTRIBUTING.md)).
 See [`docs/architecture.md`](https://github.com/atomsai/contextdb/blob/main/docs/architecture.md) for the design rationale. Issues and pull requests welcome on [GitHub](https://github.com/atomsai/contextdb).
 
 **Local setup:**

{pycontextdb-0.3.0 → pycontextdb-0.3.2}/README.md

@@ -552,8 +552,8 @@ pip install 'pycontextdb[postgres]'
 db = contextdb.init(storage_url="postgresql://...")
 ```
 
-See [docs/serve.md](docs/serve.md), [docs/multi_tenant.md](docs/multi_tenant.md),
-and [docs/trust_policy.md](docs/trust_policy.md).
+See [docs/serve.md](https://github.com/atomsai/contextdb/blob/main/docs/serve.md), [docs/multi_tenant.md](https://github.com/atomsai/contextdb/blob/main/docs/multi_tenant.md),
+and [docs/trust_policy.md](https://github.com/atomsai/contextdb/blob/main/docs/trust_policy.md).
 
 ## License and attribution
 
@@ -562,14 +562,16 @@ this README ships in this tree, with no feature gates. **ContextDB** is a
 trademark; the Apache license is not a trademark license. Reselling
 ContextDB as a service, or as part of one, under the ContextDB name or
 branding requires a commercial agreement with Atoms AI — contact
-contextdb@atomsai.com (see [COMMERCIAL.md](COMMERCIAL.md)). A public
+contextdb@atomsai.com (see [COMMERCIAL.md](https://github.com/atomsai/contextdb/blob/main/COMMERCIAL.md)).
+The binding product boundary is documented in
+[OPEN_CORE.md](https://github.com/atomsai/contextdb/blob/main/OPEN_CORE.md). A public
 credit line is optional — if you want one, use **Built with ContextDB**
 linking to this repository.
 
 ## Contributing
 
 Apache 2.0 — see [LICENSE](https://github.com/atomsai/contextdb/blob/main/LICENSE).
-Substantial PRs need a CLA ([CONTRIBUTING.md](CONTRIBUTING.md)).
+Substantial PRs need a CLA ([CONTRIBUTING.md](https://github.com/atomsai/contextdb/blob/main/CONTRIBUTING.md)).
 See [`docs/architecture.md`](https://github.com/atomsai/contextdb/blob/main/docs/architecture.md) for the design rationale. Issues and pull requests welcome on [GitHub](https://github.com/atomsai/contextdb).
 
 **Local setup:**

{pycontextdb-0.3.0 → pycontextdb-0.3.2}/contextdb/__init__.py

@@ -14,12 +14,14 @@ from contextdb.core.exceptions import (
     PrivacyError,
     ScopeConflictError,
     SourceRequiredError,
+    StaleReadError,
     StorageError,
     UnauthorizedError,
 )
 from contextdb.core.models import (
     Edge,
     Entity,
+    MemoryConsistencyToken,
     MemoryItem,
     MemoryStatus,
     MemoryType,
@@ -29,8 +31,9 @@ from contextdb.core.models import (
 )
 from contextdb.core.policy import TrustPolicy
 from contextdb.pool import ContextDBPool
+from contextdb.utils.embeddings import EmbeddingProvider
 
-__version__ = "0.3.0"
+__version__ = "0.3.2"
 
 __all__ = [
     "Clock",
@@ -40,9 +43,11 @@ __all__ = [
     "ContextDBError",
     "ContextDBPool",
     "Edge",
+    "EmbeddingProvider",
     "Entity",
     "FrozenClock",
     "MemoryItem",
+    "MemoryConsistencyToken",
     "MemoryNotFoundError",
     "MemoryStatus",
     "MemoryType",
@@ -52,6 +57,7 @@ __all__ = [
     "RetentionPolicy",
     "ScopeConflictError",
     "SourceRequiredError",
+    "StaleReadError",
     "StorageError",
     "TrustPolicy",
     "UnauthorizedError",
@@ -70,6 +76,8 @@ def init(
     session_id: str | None = None,
     clock: Clock | None = None,
     trust_policy: TrustPolicy | None = None,
+    postgres_pool: Any | None = None,
+    embedding_provider: EmbeddingProvider | None = None,
     **kwargs: Any,
 ) -> ContextDB:
     """Create a :class:`ContextDB` client.
@@ -84,6 +92,10 @@ def init(
         config: Pre-built configuration. When ``None`` one is constructed
             from ``kwargs`` and environment variables prefixed with
             ``CONTEXTDB_``.
+        postgres_pool: Optional externally owned asyncpg pool. Valid only with
+            a PostgreSQL ``storage_url``. ContextDB never closes this pool.
+        embedding_provider: Optional externally owned provider shared by the
+            host. ContextDB uses but never closes this provider.
         **kwargs: Forwarded to :class:`ContextDBConfig` if ``config`` is
             not provided.
 
@@ -99,4 +111,6 @@ def init(
         session_id=session_id,
         clock=clock,
         trust_policy=trust_policy,
+        postgres_pool=postgres_pool,
+        embedding_provider=embedding_provider,
     )