memvara 0.1.0__tar.gz

memvara-0.1.0/.dockerignore

@@ -0,0 +1,19 @@
+# Deny everything, then name what the build actually needs. The allow-list direction is
+# deliberate: a deny-list forgets, and the things it forgets here are `.git` (the whole
+# history, in every layer that touches the context), `.coverage`, and — the one that
+# matters — any `memory.db` a developer left in the tree. A memory store is user data,
+# and shipping one inside a published image is a data leak that no later `RUN rm` undoes,
+# because the file is already in the layer beneath it.
+*
+
+# `pyproject.toml` names `readme` and `license-files`, so hatchling fails the build
+# without these two present; they are not optional niceties.
+!pyproject.toml
+!README.md
+!LICENSE
+!memvara
+
+# Byte-compiled from the host, and possibly for a different interpreter than the image
+# runs. `pip install` compiles fresh inside the builder.
+memvara/**/__pycache__
+memvara/**/*.pyc

memvara-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,63 @@
+name: Bug report
+description: Something behaves differently from what the docs say
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **Not for security issues.** Vulnerabilities go through the private advisory flow
+        in [SECURITY.md](https://github.com/memvara/memvara/blob/main/SECURITY.md), not here.
+
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened, and what you expected instead
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Reproduction
+      description: >
+        A script we can run. It must work offline with no API key — everything in this
+        library does, so a repro that needs a network call almost always means the bug is
+        somewhere else. Use `Memvara(":memory:")` and pass explicit `datetime` values
+        rather than relying on the clock.
+      render: python
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: memvara version
+      description: "`python3 -c 'import memvara; print(memvara.__version__)'`, or the commit if you installed from a checkout."
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      description: "`python3 -V`"
+    validations:
+      required: true
+
+  - type: input
+    id: platform
+    attributes:
+      label: Platform
+      description: "OS and architecture — e.g. macOS 15 arm64, Ubuntu 24.04 x86_64, Windows 11."
+    validations:
+      required: true
+
+  - type: textarea
+    id: config
+    attributes:
+      label: Non-default configuration
+      description: >
+        Any `embedder=`, `llm=`, `store=`, `redactor=` or scope arguments, and whether the
+        store is on disk or `:memory:`. Skip if everything was default.
+    validations:
+      required: false

memvara-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/memvara/memvara/security/advisories/new
+    about: Private advisory, not a public issue. See SECURITY.md for what is in scope.

memvara-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,50 @@
+name: Feature request
+description: Propose something the library should do
+labels: [enhancement]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Before writing code, read
+        [Scope](https://github.com/memvara/memvara/blob/main/CONTRIBUTING.md#scope) in
+        CONTRIBUTING.md. It says what is likely to be accepted, and — with a four-question
+        test you can apply yourself — what belongs in the separate commercial layer and
+        will be declined here even if it is good. Better to find that out now than after
+        the PR.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What can't you do today
+      description: The problem, not the solution. What did you try, and where did it stop?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What you'd like instead
+      description: >
+        A sketch of the API is enough. If it changes bitemporal semantics, the predicate
+        schema, retrieval scoring, scope resolution, or what `why()` returns, say so —
+        those are load-bearing and the discussion is different.
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: memvara version
+      description: So we know whether it already exists.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: What you ruled out
+      description: >
+        Including whether this can be done today behind one of the existing protocols
+        (`Store`, `Embedder`, `LLM`, `Recorder`, `Redactor`) without a change to the core.
+    validations:
+      required: false

memvara-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,122 @@
+# The suite enforces `fail_under = 100`. Until this workflow existed it enforced it on
+# exactly one developer machine running one Python — which is not enforcement, it is a
+# local habit. The matrix is the point: `requires-python = ">=3.10"` is a promise, and
+# 3.10 through 3.12 had never executed a line of this library.
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  # A second push to the same branch makes the first run's answer irrelevant.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: py${{ matrix.python }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      # Never cancel siblings: "3.10 fails and 3.13 passes" is the single most useful
+      # thing this matrix can tell us, and fail-fast throws it away.
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+        os: [ubuntu-latest]
+        include:
+          # Two more OSes on one version each. The store touches mmap, file locking and
+          # path handling — all three differ on Windows, and none of it is exercised by
+          # running Linux four times.
+          - python: "3.13"
+            os: macos-latest
+          - python: "3.13"
+            os: windows-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Test
+        run: python -m pytest -q
+
+  coverage:
+    # Separate job, one version. Coverage is a property of the suite, not of the
+    # interpreter, so measuring it four times would just be four chances to flake.
+    name: coverage (gated at 100%)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+      - run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+      # `coverage report` exits non-zero below fail_under, so this step is the gate.
+      - run: |
+          python -m coverage run -m pytest -q
+          python -m coverage report
+
+  types:
+    # The package ships `py.typed`, so these annotations are what a user's checker
+    # consumes — and `search()` is `@overload`ed, which is the kind of declaration that
+    # can be wrong in a way no runtime test notices: a bad overload type-checks a call
+    # that then fails. The overload tests skip without mypy installed, so without this
+    # job they were enforced only on machines that happened to have it.
+    name: mypy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+      - run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+      - run: python -m mypy -p memvara
+
+  offline:
+    # The headline claim is "numpy and nothing else, runs offline with no API key". That
+    # is worth testing rather than asserting: install the bare package with no extras and
+    # import every module, so an accidental top-level `import anthropic` in some adapter
+    # cannot pass CI.
+    name: core imports with no extras
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: |
+          python -m pip install --upgrade pip
+          python -m pip install .
+      - name: Import every module from a directory that is not the repo
+        run: |
+          cd /tmp
+          python -c "
+          import importlib, pkgutil, memvara
+          failed = []
+          for m in pkgutil.walk_packages(memvara.__path__, 'memvara.'):
+              try:
+                  importlib.import_module(m.name)
+              except ImportError as e:
+                  # Optional adapters may import their provider lazily; a hard failure
+                  # here means a top-level dependency leaked into the core install.
+                  failed.append((m.name, str(e)))
+          assert not failed, failed
+          print('all modules import with numpy alone')
+          "

memvara-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+dist/
+.coverage
+__pycache__/
+*.pyc
+.pytest_cache/
+
+# Local editor/agent scratch. `.claude/launch.json` names an absolute path on one
+# machine, so it is configuration for a workstation rather than for the project.
+.claude/
+
+# Secrets never belong in a repository, and this one is Apache-2.0 and public: a commit
+# here is a disclosure, not a mistake to be fixed by a later commit. Listed even though
+# nothing in this repo reads a `.env`, because the rule has to exist *before* the file
+# does — an ignore added after `git add -A` protects nothing.
+.env
+.env.*
+!.env.example