docsgraph 0.1.0a2__tar.gz

docsgraph-0.1.0a2/.cairn/config.toml

@@ -0,0 +1,40 @@
+# Cairn repository documentation index.
+# Paths are relative to the repository root.
+documents_dir = "documents"
+enable_markitdown = false
+search_sections_per_doc = 1
+primary_doc = "readme"
+
+include = [
+  "*.md",
+  "*.markdown",
+  "*.mdown",
+  "*.mkd",
+  "*.pdf",
+  "*/README.md",
+  "*/README.markdown",
+  "docs/**/*.md",
+  "docs/**/*.markdown",
+  "docs/**/*.mdown",
+  "docs/**/*.mkd",
+  "docs/**/*.pdf",
+]
+
+exclude = [
+  ".git/**",
+  ".cairn/**",
+  ".codegraph/**",
+  ".hypothesis/**",
+  ".mypy_cache/**",
+  ".pytest_cache/**",
+  ".ruff_cache/**",
+  ".venv/**",
+  ".tox/**",
+  ".nox/**",
+  "venv/**",
+  "node_modules/**",
+  "dist/**",
+  "build/**",
+  "site/**",
+  "__pycache__/**",
+]

docsgraph-0.1.0a2/.env.example

@@ -0,0 +1,48 @@
+# Cairn environment example.
+# Copy to .env for local experiments. Never commit real API keys.
+
+# ---------------------------------------------------------------------------
+# Local defaults: Ollama-compatible summarization + embeddings
+# ---------------------------------------------------------------------------
+# CAIRN_LLM_BASE_URL=http://localhost:11434/v1
+# CAIRN_LLM_MODEL=qwen2.5:7b
+# CAIRN_LLM_API_KEY=ollama
+#
+# CAIRN_EMBED_PROVIDER=openai-compatible
+# CAIRN_EMBED_BASE_URL=http://localhost:11434/v1
+# CAIRN_EMBED_MODEL=nomic-embed-text
+# CAIRN_EMBED_API_KEY=ollama
+
+# ---------------------------------------------------------------------------
+# OpenAI-compatible hosted endpoint
+# ---------------------------------------------------------------------------
+# CAIRN_LLM_BASE_URL=https://api.example.com/v1
+# CAIRN_LLM_MODEL=your-chat-model
+# CAIRN_LLM_API_KEY=replace-me
+#
+# CAIRN_EMBED_PROVIDER=openai-compatible
+# CAIRN_EMBED_BASE_URL=https://api.example.com/v1
+# CAIRN_EMBED_MODEL=your-embedding-model
+# CAIRN_EMBED_API_KEY=replace-me
+
+# ---------------------------------------------------------------------------
+# Volcengine ARK / Doubao
+# ---------------------------------------------------------------------------
+# CAIRN_LLM_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
+# CAIRN_LLM_MODEL=doubao-seed-2-0-code-preview-260215
+# CAIRN_LLM_API_KEY=replace-me
+#
+# CAIRN_EMBED_PROVIDER=doubao-vision
+# CAIRN_EMBED_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
+# CAIRN_EMBED_MODEL=doubao-embedding-vision-251215
+# CAIRN_EMBED_API_KEY=replace-me
+
+# ---------------------------------------------------------------------------
+# Hosted API stability knobs
+# ---------------------------------------------------------------------------
+# CAIRN_LLM_TIMEOUT=60
+# CAIRN_LLM_MAX_RETRIES=2
+# CAIRN_EMBED_TIMEOUT=60
+# CAIRN_EMBED_MAX_RETRIES=2
+# CAIRN_SUMMARY_CONCURRENCY=4
+# CAIRN_EMBED_BATCH_SIZE=32

docsgraph-0.1.0a2/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,65 @@
+name: Bug report
+description: Something Cairn does, but shouldn't (or doesn't, but should).
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time. Please fill in the boxes below — the
+        more concrete the reproducer, the faster the fix.
+
+  - type: input
+    id: version
+    attributes:
+      label: Cairn version
+      description: Output of `cairn version` (or your installed package version).
+      placeholder: "0.1.0a1"
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.12.3"
+    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: reproducer
+    attributes:
+      label: Minimal reproducer
+      description: A short markdown file, a shell command, or a Python snippet that triggers the issue.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: Include any error output. If `cairn serve` is involved, the JSON-line log is very helpful.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: extras
+    attributes:
+      label: Additional context
+      description: Endpoint configuration (Ollama / OpenAI / other), document size, anything else relevant.

docsgraph-0.1.0a2/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security disclosure
+    url: https://github.com/jokeuncle/cairn/blob/main/SECURITY.md
+    about: Report a security issue privately — please do not open a public issue.
+  - name: Architecture decisions
+    url: https://github.com/jokeuncle/cairn/tree/main/docs/decisions
+    about: Browse existing ADRs before proposing structural changes.

docsgraph-0.1.0a2/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,55 @@
+name: Feature request
+description: Propose a change to Cairn.
+labels: ["enhancement", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Before opening a feature request, please read
+        [`PRODUCT.md`](https://github.com/jokeuncle/cairn/blob/main/PRODUCT.md)
+        — especially §6 (Non-goals). The project is deliberately
+        opinionated, and proposals that contradict the thesis or expand
+        the scope beyond structured-document retrieval are unlikely to
+        land.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem are you trying to solve?
+      description: Describe the user-facing problem first, the proposed solution second.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Sketch the API or behavior. If it touches the MCP tool catalog, sub-index format, or layer boundaries, an ADR will be required before code.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: What else did you look at, and why was it not enough?
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Which subsystem does this touch?
+      multiple: true
+      options:
+        - Markdown ingest
+        - PDF ingest
+        - Summaries (S)
+        - Vectors (V)
+        - Entities (E)
+        - Cross-references (X)
+        - Tools / MCP server
+        - CLI
+        - Bench
+        - Documentation
+        - Other (please describe in "Proposed solution")
+    validations:
+      required: true

docsgraph-0.1.0a2/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,50 @@
+<!--
+  Thanks for opening a PR! Before you submit, please make sure the items
+  below are taken care of. CI will catch most of them, but it helps
+  reviewers move faster if you've already verified them locally.
+-->
+
+## Summary
+
+<!-- One sentence: what changes and why. -->
+
+## Type of change
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] Feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that changes existing behavior)
+- [ ] Documentation only
+- [ ] Refactor / internal cleanup
+
+## Linked ADR / Roadmap milestone
+
+<!--
+  If this PR touches PRODUCT.md, ARCHITECTURE.md, the MCP tool catalog,
+  or on-disk formats, an ADR is required. Link it here.
+  Otherwise reference the ROADMAP milestone (e.g. "v0.2.5").
+-->
+
+## Test plan
+
+<!--
+  Walk through what you ran locally. Concrete commands beat "I tested it".
+-->
+
+```
+ruff check src tests
+mypy src/cairn
+pytest tests/unit -q
+```
+
+- [ ] Unit tests added / updated
+- [ ] CHANGELOG.md updated (for user-facing changes)
+
+## Anti-checklist (CLAUDE.md anti-patterns)
+
+The following are non-goals; check that this PR does **not**:
+
+- [ ] Add a chatbot / answer-generation tool to the public catalog
+- [ ] Replace structure-aware retrieval with vector-chunking as the primary path
+- [ ] Change progressive-disclosure defaults to return more by default
+- [ ] Introduce a network dependency in the default install
+- [ ] Pull a heavy dependency without an ADR

docsgraph-0.1.0a2/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5

docsgraph-0.1.0a2/.github/workflows/ci.yml

@@ -0,0 +1,72 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Cancel in-progress runs of the same workflow on the same branch/PR.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-types-tests:
+    name: lint + types + tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package + dev extras
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: ruff
+        run: ruff check .
+
+      - name: mypy --strict
+        run: mypy src tests
+
+      - name: pytest
+        run: pytest
+
+  build:
+    name: build wheel + sdist
+    runs-on: ubuntu-latest
+    needs: lint-types-tests
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade pip build twine
+
+      - name: Build distributions
+        run: python -m build --wheel --sdist
+
+      - name: Check distributions
+        run: python -m twine check dist/*
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: cairn-dist
+          path: dist/*
+          retention-days: 14

docsgraph-0.1.0a2/.github/workflows/release.yml

@@ -0,0 +1,77 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build wheel + sdist for ${{ github.ref_name }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade pip build twine
+
+      - name: Build distributions
+        run: python -m build --wheel --sdist
+
+      - name: Check distributions
+        run: python -m twine check dist/*
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: build
+    # Trusted publishing — requires the PyPI project to opt into
+    # GitHub OIDC publishing under Settings → Publishing.
+    # Until then, leave this job disabled by editing the `if`.
+    if: ${{ false }}
+    environment:
+      name: pypi
+      url: https://pypi.org/p/cairn
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Attach artifacts to GitHub release
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      contents: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+          draft: false
+          prerelease: ${{ contains(github.ref_name, '-') || contains(github.ref_name, 'a') || contains(github.ref_name, 'b') || contains(github.ref_name, 'rc') }}

docsgraph-0.1.0a2/.github/workflows/repo-regression.yml

@@ -0,0 +1,36 @@
+name: Repo regression
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "23 3 * * *"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  public-repo-regression:
+    name: public repo regression
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install package + dev extras
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Labeled repo eval
+        run: python scripts/eval_repos.py --repo all --strict
+
+      - name: Broad repo smoke
+        run: python scripts/smoke_many_repos.py --limit 37 --strict

docsgraph-0.1.0a2/.gitignore

@@ -0,0 +1,82 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual envs
+.venv/
+venv/
+env/
+ENV/
+
+# Testing / coverage
+.pytest_cache/
+.hypothesis/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+
+# Linting / typing
+.mypy_cache/
+.ruff_cache/
+.pyre/
+
+# Tooling
+.uv/
+.codegraph/
+uv.lock
+.python-version
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Cairn runtime data
+.cairn/documents/
+.cairn/manifest.json
+.cairn/inspector.html
+*.lancedb/
+*.sqlite
+*.sqlite-*
+
+# Secrets
+.env
+.env.*
+!.env.example
+
+# Logs
+*.log
+logs/
+
+# Local agent runs / benchmarks output
+runs/
+results/
+benchmarks/output/