enclave-ontos 0.1.0__tar.gz

enclave_ontos-0.1.0/.env.example

@@ -0,0 +1,118 @@
+# Ontos environment configuration
+#
+# Copy to `.env` (git-ignored) and fill in the values you actually need.
+# Values are grouped by milestone so you only set what your target
+# milestone requires. M0 needs almost nothing.
+#
+# Sovereignty rule: any variable marked [BRIDGE] sends data outside the
+# customer VPC and is a temporary dev convenience. Production deploys
+# resolve every [BRIDGE] to a customer-controlled endpoint (Ollama /
+# Bedrock / Azure OpenAI / Vertex) or to Enclave Scribe once Scribe
+# passes benchmarks.
+
+
+# ────────────────────────────────────────────────────────────────
+# M0 — running today
+# ────────────────────────────────────────────────────────────────
+
+# Required in prod. In dev (ONTOS_ENV != "prod") the runtime auto-defaults
+# to a loud placeholder — do NOT ship that placeholder to a customer.
+# In prod, derive this from KMS (or the customer's key vault) at boot.
+ONTOS_AUDIT_SIGNING_KEY=dev-only-signing-key-do-not-use
+
+# Set to "prod" to make the runtime refuse to boot without a real
+# signing key. Anything else (or unset) is dev mode.
+ONTOS_ENV=dev
+
+# Where the MCP server binds. 127.0.0.1 for local dev; 0.0.0.0 in a
+# container behind a reverse proxy.
+ONTOS_LISTEN_HOST=127.0.0.1
+ONTOS_LISTEN_PORT=8765
+
+# Which storage backend to use. M0 only supports "networkx" (in-memory).
+# M1 adds "neo4j"; M2 adds "kuzu" (LadybugDB) and "neptune".
+ONTOS_STORAGE_BACKEND=networkx
+
+# Where the audit chain persists. SQLite default is fine for dev.
+# M2 swaps to Postgres for regulated deploys (6+ month retention).
+ONTOS_AUDIT_DB_URL=sqlite+pysqlite:///./audit-logs/audit.sqlite
+
+# Name of the env var the runtime reads for the signing key.
+# You almost never need to change this — it exists so a deploy can
+# rename the concrete env var (e.g. to match a k8s secret's key).
+ONTOS_AUDIT_SIGNING_KEY_ENV=ONTOS_AUDIT_SIGNING_KEY
+
+# Optional: path to a YAML/LinkML ontology file. If unset, the runtime
+# runs schemaless (M0 default).
+# ONTOS_ONTOLOGY_PATH=./docs/ontology/examples/fintech.yaml
+
+
+# ────────────────────────────────────────────────────────────────
+# M1 — Neo4j storage + first extraction wrappers
+# ────────────────────────────────────────────────────────────────
+
+# Neo4j — self-hosted, Aura, or in-VPC cluster the customer runs.
+# NEO4J_URI=bolt://localhost:7687
+# NEO4J_USER=neo4j
+# NEO4J_PASSWORD=
+
+# LLM for extraction — pick exactly ONE of the three blocks below.
+
+# Option A [BRIDGE]: OpenAI. Fastest to test; violates in-VPC promise.
+# OPENAI_API_KEY=sk-...
+# OPENAI_MODEL=gpt-4o-mini
+
+# Option B [BRIDGE]: Anthropic. Better structured extraction than OpenAI.
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_MODEL=claude-sonnet-5
+
+# Option C: Ollama (fully local, no key). This is the sovereignty-preserving
+# path and the shape Scribe eventually replaces.
+# OLLAMA_HOST=http://localhost:11434
+# OLLAMA_MODEL=llama3.1:8b
+
+# Embedding model. BGE-m3 runs locally via sentence-transformers.
+# EMBEDDING_MODEL=BAAI/bge-m3
+
+# When Enclave Scribe is ready and beats frontier benchmarks, these
+# replace every extraction key above:
+# SCRIBE_ENDPOINT=http://scribe.ontos.svc.cluster.local:9000
+# SCRIBE_MODEL=scribe-v1
+
+
+# ────────────────────────────────────────────────────────────────
+# M2 — permission-aware traversal + persistent audit
+# ────────────────────────────────────────────────────────────────
+
+# OpenFGA (default authz backend). Self-host in-VPC, or point at
+# openfga.dev's hosted plane for dev.
+# FGA_API_URL=http://localhost:8080
+# FGA_STORE_ID=
+# FGA_API_TOKEN=
+
+# Alternative: SpiceDB (Authzed). Pick one, not both.
+# SPICEDB_ENDPOINT=localhost:50051
+# SPICEDB_TOKEN=
+
+# Postgres for the persistent hash-chained audit log (replaces the M0
+# SQLite default). Regulated deploys must retain ≥6 months.
+# ONTOS_AUDIT_DB_URL=postgresql+psycopg://ontos:changeme@postgres:5432/ontos_audit
+
+
+# ────────────────────────────────────────────────────────────────
+# M4 — real source connectors (per customer, per tenant, not global)
+# ────────────────────────────────────────────────────────────────
+#
+# These are examples of what a connector config will look like — the
+# real system will load per-tenant credentials from a secure store,
+# not from process env. Do not put customer credentials here.
+#
+# SLACK_BOT_TOKEN=xoxb-...
+# GOOGLE_DRIVE_CLIENT_ID=
+# GOOGLE_DRIVE_CLIENT_SECRET=
+# CONFLUENCE_API_TOKEN=
+# JIRA_API_TOKEN=
+# SALESFORCE_CLIENT_ID=
+# SALESFORCE_CLIENT_SECRET=
+# GITHUB_APP_ID=
+# GITHUB_PRIVATE_KEY=

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

@@ -0,0 +1,88 @@
+name: Bug report
+description: Something in Ontos doesn't work as documented.
+title: "[bug] "
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the report. Please fill in what you can — every field
+        makes triage faster.
+
+        **Do NOT file a security vulnerability here.** See
+        [SECURITY.md](../blob/main/SECURITY.md) for the private
+        disclosure path.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What you saw, and what you expected instead.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: |
+        The smallest snippet, commands, or steps that reliably reproduce
+        the issue. If you can't produce a MRE, describe the shape of what
+        you were doing instead.
+      render: bash
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Ontos version / commit
+      description: Output of `uv pip show ontos` or the commit SHA you're on.
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      description: Output of `python --version`.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: storage-backend
+    attributes:
+      label: Storage backend
+      options:
+        - networkx (M0 in-memory)
+        - neo4j
+        - kuzu / ladybugdb
+        - neptune
+        - other / n/a
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs / stack trace
+      description: |
+        Paste any relevant structured log output or a stack trace. Redact
+        anything that looks like a customer identifier, credential, or
+        piece of regulated data before pasting.
+      render: text
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: touches-compliance
+    attributes:
+      label: Does this touch a compliance property?
+      description: Tick every one that applies. This routes the bug to the right reviewer.
+      options:
+        - label: Audit chain (Article 12)
+        - label: Permission-aware traversal / node-existence leaks
+        - label: Bitemporal correctness (`as_of` returns wrong facts)
+        - label: Provenance metadata (missing / forged / dropped)
+        - label: Sovereignty (unexpected outbound network call)
+        - label: None of the above

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

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/getenclave/ontos/blob/main/SECURITY.md
+    about: Do NOT open a public issue. Follow the private disclosure path in SECURITY.md.
+  - name: Question / help / design discussion
+    url: https://github.com/getenclave/ontos/discussions
+    about: Use GitHub Discussions for questions and open-ended design conversation.
+  - name: Enclave (the parent product)
+    url: https://getenclave.ai
+    about: Ontos is a subset of Enclave. For anything about the wider Enclave platform, start here.

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

@@ -0,0 +1,74 @@
+name: Feature / proposal
+description: Suggest a new capability, connector, backend, or design change.
+title: "[proposal] "
+labels: ["proposal", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the idea. Before you start writing code for anything
+        architectural (new module, new storage backend, new authz backend,
+        new extractor family), please open this issue first so we can
+        align on the design.
+
+        Small fixes, docs, tests, and connector adapters don't need a
+        proposal issue — just open a PR.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve
+      description: |
+        Describe the user or operational pain first. Do NOT lead with a
+        proposed solution — the shape of the fix follows from the shape
+        of the problem.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed
+    attributes:
+      label: Proposed approach
+      description: |
+        Rough sketch of the change. Modules touched, new data shapes,
+        MCP surface changes, config surface changes. Details welcome
+        but not required.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives you considered
+      description: What else could solve this, and why the proposed approach wins.
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: invariants
+    attributes:
+      label: Which invariants does this touch?
+      description: Tick every one this proposal changes or has to preserve.
+      options:
+        - label: Provenance on every fact
+        - label: Audit-first (every request path emits an `AuditRecord`)
+        - label: Permission-aware traversal (no node-existence leaks)
+        - label: Bitemporal immutability
+        - label: Sovereignty (no outbound calls to non-configured hosts)
+        - label: Extractor interface stays a drop-in for enclave-scribe
+        - label: None of the above
+
+  - type: dropdown
+    id: milestone
+    attributes:
+      label: Which milestone does this target
+      options:
+        - "M0 (scaffolding, in-memory storage)"
+        - "M1 (Neo4j + extraction wrappers)"
+        - "M2 (OpenFGA / persistent audit)"
+        - "M3 (planner/executor split, PPR, PathRAG-style pruning)"
+        - "M4 (bitemporal writes, ER cascade, connectors)"
+        - "v0 GA (design partner ready)"
+        - "Not sure — you tell me"
+    validations:
+      required: true

enclave_ontos-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,60 @@
+<!--
+Thanks for contributing to Ontos!
+
+Please fill in every section below. If a section genuinely doesn't apply,
+write "n/a" and one line saying why — don't delete it.
+
+Compliance-critical PRs (anything touching authz, audit, or provenance)
+must include tests under tests/compliance/.
+-->
+
+## Why
+
+<!-- The problem this PR solves. Link the issue if one exists (Fixes #NNN). -->
+
+## What
+
+<!-- The change, in 3–5 bullets. Reviewers should not have to read the
+     diff to know the shape of what changed. -->
+
+## Non-negotiables checklist
+
+<!-- Tick every box that applies. If you had to weaken any invariant,
+     explain in "Notes for reviewer" below. -->
+
+- [ ] Every new `Fact` written to the store carries full `Provenance`.
+- [ ] Every code path that returns data to an agent emits an `AuditRecord` before returning.
+- [ ] No permission post-filtering added; traversal-time checks preserved; no node-existence leaks.
+- [ ] No in-place `Fact` mutation; corrections use `close_fact(...)` supersession.
+- [ ] No outbound network calls to hosts the operator did not configure; no telemetry to Enclave-operated services.
+- [ ] Extractor interface remains a drop-in for `enclave-scribe` — no LlamaIndex/LangChain-specific types leak past `ontos/extraction/`.
+
+## Tests
+
+<!-- List what you added/changed under tests/. Compliance-critical PRs
+     MUST land with matching tests under tests/compliance/. -->
+
+- [ ] Unit tests added / updated
+- [ ] Compliance tests added / updated (required if this touches authz, audit, or provenance)
+- [ ] Integration tests added / updated
+- [ ] Benchmarks updated (if this changes retrieval quality or latency)
+
+## Verification
+
+<!-- The exact commands you ran to convince yourself this works. -->
+
+```bash
+uv run ruff check ontos tests
+uv run mypy ontos
+uv run pytest -q
+```
+
+## Notes for reviewer
+
+<!-- Anything the reviewer needs to know that isn't obvious from the diff:
+     tradeoffs you considered, alternatives you rejected, follow-ups you
+     plan for a later PR. -->
+
+## DCO
+
+- [ ] I have signed off every commit (`git commit -s`) per the [DCO](https://developercertificate.org/).

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

@@ -0,0 +1,67 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# Cancel superseded runs on the same branch/PR so a fast rebase doesn't
+# leave a stale run consuming a runner.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: lint · type-check · test
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          # Cache the uv download index + wheel cache across runs on the
+          # same branch. Cache key is derived from uv.lock so a lock
+          # change forces a clean install.
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python (from .python-version)
+        run: uv python install
+
+      - name: Install dependencies
+        run: uv sync --extra dev --frozen
+
+      - name: Ruff (lint)
+        run: uv run ruff check ontos tests
+
+      - name: Mypy (strict type-check)
+        run: uv run mypy ontos
+
+      - name: Pytest (unit + compliance)
+        run: uv run pytest -q -m "not integration and not benchmark"
+
+      - name: Pytest (integration — Neo4j via Testcontainers)
+        run: uv run pytest -q -m "integration and not benchmark"
+
+      - name: Set up Helm
+        uses: azure/setup-helm@v4
+        with:
+          version: v3.16.0
+
+      - name: Helm lint (deploy/helm/ontos)
+        run: helm lint deploy/helm/ontos
+
+      - name: Helm template renders (deploy/helm/ontos)
+        # `--dry-run=client` skips the API server; we just want to
+        # prove every template compiles into valid YAML.
+        run: helm template ontos deploy/helm/ontos > /dev/null

enclave_ontos-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,173 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Build and validate everything; skip PyPI + GHCR pushes."
+        type: boolean
+        default: true
+
+permissions:
+  contents: write   # for creating the GitHub Release
+  packages: write   # for pushing to GHCR
+  id-token: write   # for PyPI trusted publishing (OIDC)
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build wheels + verify version
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Extract version from tag
+        id: version
+        run: |
+          if [[ "${{ github.ref }}" == refs/tags/v* ]]; then
+            VERSION="${GITHUB_REF#refs/tags/v}"
+          else
+            # workflow_dispatch: dry-run; use whatever's in _version.py
+            VERSION="$(python -c "import runpy; print(runpy.run_path('ontos/_version.py')['__version__'])")"
+          fi
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "Building Ontos v${VERSION}"
+
+      - name: Verify tag matches ontos/_version.py
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          FILE_VERSION="$(python -c "import runpy; print(runpy.run_path('ontos/_version.py')['__version__'])")"
+          TAG_VERSION="${{ steps.version.outputs.version }}"
+          if [[ "$FILE_VERSION" != "$TAG_VERSION" ]]; then
+            echo "ERROR: git tag v${TAG_VERSION} does not match ontos/_version.py (${FILE_VERSION})"
+            exit 1
+          fi
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v') && !inputs.dry_run
+    environment:
+      name: pypi
+      url: https://pypi.org/project/enclave-ontos/${{ needs.build.outputs.version }}
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI via trusted publishing
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # No password / API token: uses OIDC trusted publishing. Set up
+        # the PyPI project once at pypi.org → Manage → Publishing →
+        # Add a new publisher, GitHub, this repo, workflow=release.yml,
+        # environment=pypi. See RELEASING.md.
+
+  publish-ghcr:
+    name: Build + push container to GHCR
+    needs: build
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v') && !inputs.dry_run
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Compute image tags
+        id: meta
+        run: |
+          VERSION="${{ needs.build.outputs.version }}"
+          IMAGE="ghcr.io/${{ github.repository_owner }}/ontos"
+          # Force lowercase — GHCR requires lowercase image names.
+          IMAGE="${IMAGE,,}"
+          echo "image=${IMAGE}" >> "$GITHUB_OUTPUT"
+          echo "tag_version=${IMAGE}:${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "tag_latest=${IMAGE}:latest" >> "$GITHUB_OUTPUT"
+
+      - name: Build + push image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: deploy/Dockerfile
+          push: true
+          tags: |
+            ${{ steps.meta.outputs.tag_version }}
+            ${{ steps.meta.outputs.tag_latest }}
+          labels: |
+            org.opencontainers.image.source=https://github.com/${{ github.repository }}
+            org.opencontainers.image.version=${{ needs.build.outputs.version }}
+            org.opencontainers.image.revision=${{ github.sha }}
+
+  gh-release:
+    name: Create GitHub Release
+    needs: [build, publish-pypi, publish-ghcr]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v') && !inputs.dry_run
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Extract CHANGELOG section for this version
+        id: notes
+        run: |
+          VERSION="${{ needs.build.outputs.version }}"
+          # Extract the section between `## [VERSION]` and the next `## [`.
+          awk -v v="[$VERSION]" '
+            $0 ~ "^## " v { flag=1; next }
+            flag && /^## \[/ { flag=0 }
+            flag { print }
+          ' CHANGELOG.md > release_notes.md
+          if [[ ! -s release_notes.md ]]; then
+            echo "WARNING: no CHANGELOG section for v${VERSION}; using a stub" >&2
+            echo "See CHANGELOG.md for details." > release_notes.md
+          fi
+
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          body_path: release_notes.md
+          files: dist/*
+          fail_on_unmatched_files: true

enclave_ontos-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+*.db
+*.sqlite
+*.sqlite3
+runtime-data/
+audit-logs/
+.DS_Store
+.idea/
+.vscode/
+dist/
+build/

enclave_ontos-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12