engrama 0.13.0__tar.gz

engrama-0.13.0/.env.example

@@ -0,0 +1,71 @@
+# Engrama — environment variables
+# Copy this file to .env and edit as needed.
+#
+# IMPORTANT: .env is in .gitignore — never commit real credentials.
+#
+# The base install runs on SQLite with zero external services. Skip down
+# to "Optional: Neo4j backend" only if you've decided you need Neo4j
+# (see BACKENDS.md for the decision guide).
+
+# === Default backend: SQLite + sqlite-vec (DDR-004) ===
+# Storage lives in a single file under your home directory. Override
+# the path if you want to keep it elsewhere.
+GRAPH_BACKEND=sqlite
+# ENGRAMA_DB_PATH=~/.engrama/engrama.db   # default; uncomment to override
+
+# === Profile (used by `engrama init`) ===
+ENGRAMA_PROFILE=developer
+
+# === Obsidian vault sync (optional) ===
+# Required for engrama_sync_note / engrama_sync_vault /
+# engrama_write_insight_to_vault. Leave it pointing at any directory if
+# you don't use Obsidian; the graph tools will still work.
+VAULT_PATH=~/Documents/vault
+
+# === Embeddings (optional, DDR-003 Phase B + DDR-004) ===
+# Providers:
+#   none    — fulltext only (default, zero-dep).
+#   ollama  — legacy convenience wrapper around Ollama's /api/embeddings.
+#   openai  — OpenAI-compatible /v1/embeddings (covers OpenAI, Ollama
+#             /v1, LM Studio, vLLM, llama.cpp, Jina, etc.).
+EMBEDDING_PROVIDER=none
+EMBEDDING_MODEL=nomic-embed-text
+EMBEDDING_DIMENSIONS=768
+
+# --- ollama provider ---
+OLLAMA_URL=http://localhost:11434
+
+# --- openai-compatible provider ---
+# Pick the base URL that matches your service.
+# OpenAI proper:        https://api.openai.com/v1
+# Ollama (OpenAI mode): http://localhost:11434/v1
+# LM Studio:            http://localhost:1234/v1
+# vLLM:                 http://localhost:8000/v1
+# llama.cpp server:     http://localhost:8080/v1
+# Jina:                 https://api.jina.ai/v1
+# OPENAI_BASE_URL=https://api.openai.com/v1
+# OPENAI_API_KEY=
+
+# === Hybrid search (DDR-003 Phase C) ===
+# Alpha controls fulltext vs vector weight (0.0 = all fulltext, 1.0 = all vector)
+HYBRID_ALPHA=0.6
+# Beta is the graph topology boost weight
+HYBRID_GRAPH_BETA=0.15
+
+
+# ============================================================
+# Optional: Neo4j backend (opt-in via `uv sync --extra neo4j`)
+# ============================================================
+# Uncomment everything below to switch to Neo4j. Make sure the
+# `neo4j` extra is installed and the database is reachable
+# (e.g. via `docker compose up -d` against the bundled
+# docker-compose.yml).
+
+# GRAPH_BACKEND=neo4j
+# NEO4J_URI=bolt://localhost:7687
+# NEO4J_USERNAME=neo4j
+# NEO4J_PASSWORD=CHANGE_ME_BEFORE_FIRST_RUN
+# NEO4J_DATABASE=neo4j
+
+# When using Neo4j with embeddings enabled, you may also want:
+# VECTOR_BACKEND=neo4j   # default for sqlite is sqlite-vec; for neo4j is none unless explicitly enabled

engrama-0.13.0/.github/CODEOWNERS

@@ -0,0 +1,20 @@
+# Auto-assigned reviewers per path.
+#
+# Lines later in the file take precedence over earlier ones, so the most
+# specific match wins. With a single maintainer today, the default rule
+# covers everything; per-path overrides exist as anchor points for future
+# co-maintainers without rewriting the file.
+#
+# Docs: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-security/customizing-your-repository/about-code-owners
+
+# Default owner for everything in the repo.
+*                                   @scops
+
+# CI, packaging and supply-chain code is load-bearing; flag it explicitly.
+/.github/                           @scops
+/pyproject.toml                     @scops
+/uv.lock                            @scops
+
+# Architecture decisions and DDRs need an owner-level signoff.
+/DDR-*.md                           @scops
+/SECURITY.md                        @scops

engrama-0.13.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,84 @@
+name: Bug report
+description: Something doesn't work the way the docs / DDRs say it should.
+title: "bug: "
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug. Please include enough
+        context that someone unfamiliar with your setup can reproduce it.
+        Security-sensitive bugs should go through [private vulnerability
+        reporting](../../security/advisories/new) instead of a public issue.
+
+  - type: input
+    id: version
+    attributes:
+      label: Engrama version
+      description: "Output of `python -c \"import engrama; print(engrama.__version__)\"`."
+      placeholder: "0.9.0"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: backend
+    attributes:
+      label: Backend in use
+      description: Which storage backend was active when the bug appeared?
+      options:
+        - SQLite (default)
+        - Neo4j
+        - Both / not sure
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.12.4"
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      placeholder: "macOS 14.5 / Ubuntu 24.04 / Windows 11"
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Minimal commands or code that trigger the bug. Smaller is better.
+      placeholder: |
+        1. `engrama init`
+        2. `engrama remember "..."`
+        3. Observed: ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behaviour
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behaviour
+      description: Include the full traceback if any. Use triple backticks for code blocks.
+    validations:
+      required: true
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Anything else?
+      description: Logs, screenshots, related issues, theories about the root cause.
+    validations:
+      required: false

engrama-0.13.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability (private)
+    url: https://github.com/scops/engrama/security/advisories/new
+    about: Report a security issue privately. Do not file a public issue.

engrama-0.13.0/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,61 @@
+name: Feature request
+description: Suggest an enhancement, new skill, new backend or API change.
+title: "feat: "
+labels: ["enhancement", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Engrama tries to stay small and opinionated. The more concretely
+        you describe the problem you're hitting, the easier it is to land
+        on a design that fits.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What are you trying to do that Engrama makes hard or impossible today?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposal
+      description: Sketch the shape — API signature, CLI flag, config key, MCP tool, schema change…
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: What else did you try or think about? Why isn't it enough?
+    validations:
+      required: false
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Where does this live?
+      multiple: true
+      options:
+        - Skills / engine
+        - SQLite backend
+        - Neo4j backend
+        - Embedding provider
+        - MCP adapter
+        - SDK / CLI
+        - Profiles / schema
+        - Docs / repo hygiene
+        - Not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Anything else?
+      description: Prior art in other projects, links to related issues / DDRs, screenshots.
+    validations:
+      required: false

engrama-0.13.0/.github/dependabot.yml

@@ -0,0 +1,92 @@
+# Dependabot configuration — see https://docs.github.com/code-security/dependabot
+#
+# Goals:
+#   - Catch security advisories on Python dependencies promptly.
+#   - Keep GitHub Actions pinned to current versions (security + features).
+#   - Avoid PR fatigue: group routine bumps into a single weekly PR per
+#     ecosystem; only security and major bumps come as their own PRs.
+
+version: 2
+
+updates:
+  # ---------------------------------------------------------------------------
+  # Python dependencies (declared in pyproject.toml; Dependabot reads uv.lock
+  # via the `pip` ecosystem, which understands PEP 621 + lockfiles).
+  # ---------------------------------------------------------------------------
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "06:00"
+      timezone: "Europe/Madrid"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "python"
+    commit-message:
+      prefix: "chore(deps)"
+      include: "scope"
+    groups:
+      # Routine patch + minor bumps batched into one PR to reduce noise.
+      python-minor-and-patch:
+        applies-to: version-updates
+        update-types:
+          - "patch"
+          - "minor"
+      # Security advisories always get their own PR (one per CVE) so they
+      # are visible and reviewable in isolation. Achieved by NOT including
+      # security-updates in any group.
+    ignore:
+      # fastmcp v3 introduces breaking changes that fail our MCP test
+      # suite (verified on PR #10, closed without merge). Stop Dependabot
+      # from re-proposing major bumps until we deliberately migrate.
+      # Patch and minor updates within v2 are still welcome.
+      - dependency-name: "fastmcp"
+        update-types:
+          - "version-update:semver-major"
+
+  # ---------------------------------------------------------------------------
+  # GitHub Actions used in .github/workflows/*.yml — keep them pinned to a
+  # current major and grab security fixes promptly.
+  # ---------------------------------------------------------------------------
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "06:00"
+      timezone: "Europe/Madrid"
+    open-pull-requests-limit: 3
+    labels:
+      - "dependencies"
+      - "github-actions"
+    commit-message:
+      prefix: "chore(ci)"
+      include: "scope"
+    groups:
+      actions-minor-and-patch:
+        applies-to: version-updates
+        update-types:
+          - "patch"
+          - "minor"
+
+  # ---------------------------------------------------------------------------
+  # Docker — currently only the Neo4j image referenced from
+  # docker-compose.yml. Less frequent (monthly) since Neo4j 5.26 is LTS and
+  # we pin to a specific minor.
+  # ---------------------------------------------------------------------------
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+      day: "monday"
+      time: "06:00"
+      timezone: "Europe/Madrid"
+    open-pull-requests-limit: 2
+    labels:
+      - "dependencies"
+      - "docker"
+    commit-message:
+      prefix: "chore(deps)"
+      include: "scope"

engrama-0.13.0/.github/pull_request_template.md

@@ -0,0 +1,37 @@
+<!--
+Thanks for the contribution! A short, focused PR is much easier to review
+than a long one. If this change is broad, consider splitting it.
+-->
+
+## Summary
+
+<!-- One or two sentences. Lead with *why*; the diff already shows *what*. -->
+
+## Backend impact
+
+<!-- Tick all that apply. Drives which CI jobs reviewers should focus on. -->
+
+- [ ] SQLite (default backend)
+- [ ] Neo4j (opt-in extra)
+- [ ] Both backends (contract / engine / skills / MCP)
+- [ ] None — docs, CI, repo hygiene, or tests only
+
+## Test plan
+
+<!--
+What did you actually run locally? Pre-checked the rows you executed.
+Add more bullets for anything specific to this change (manual MCP call,
+CLI invocation, sample script, screenshot, etc.).
+-->
+
+- [ ] `uv run ruff format --check . && uv run ruff check .`
+- [ ] `uv run pytest -q tests/backends tests/contracts tests/test_protocols.py tests/test_composable.py tests/test_openai_compat_embedder.py tests/test_cli.py`
+- [ ] Full suite with Neo4j running (only if this PR touches the Neo4j path): `uv run pytest -v`
+- [ ] Manual verification (describe):
+
+## Notes for reviewer
+
+<!--
+Open questions, follow-ups deliberately deferred, gotchas, links to
+related issues / DDRs / PRs. Leave empty if nothing applies.
+-->