cenote-core 0.1.0__tar.gz

cenote_core-0.1.0/.claude/settings.json

@@ -0,0 +1,69 @@
+{
+  "permissions": {
+    "defaultMode": "default",
+    "allow": [
+      "Read",
+      "Bash(uv sync*)",
+      "Bash(uv run pytest*)",
+      "Bash(uv run ruff*)",
+      "Bash(uv run mypy*)",
+      "Bash(uv run pre-commit*)",
+      "Bash(uv run python*)",
+      "Bash(uv build*)",
+      "Bash(uv lock*)",
+      "Bash(uv tree*)",
+      "Bash(uv pip list*)",
+      "Bash(ls *)",
+      "Bash(cat *)",
+      "Bash(head *)",
+      "Bash(tail *)",
+      "Bash(grep *)",
+      "Bash(rg *)",
+      "Bash(find *)",
+      "Bash(tree*)",
+      "Bash(wc *)",
+      "Bash(pwd)",
+      "Bash(mkdir -p *)",
+      "Bash(git status*)",
+      "Bash(git diff*)",
+      "Bash(git log*)",
+      "Bash(git branch*)",
+      "Bash(git show*)",
+      "Bash(git add *)",
+      "Bash(git restore *)",
+      "Bash(git stash*)",
+      "Bash(docker compose -f docker-compose.test.yml ps*)",
+      "Bash(docker compose -f docker-compose.test.yml logs*)"
+    ],
+    "ask": [
+      "Write",
+      "Edit",
+      "Bash(uv add*)",
+      "Bash(uv remove*)",
+      "Bash(git checkout *)",
+      "Bash(git commit *)",
+      "Bash(git merge *)",
+      "Bash(git rebase *)",
+      "Bash(git reset *)",
+      "Bash(docker compose -f docker-compose.test.yml up*)",
+      "Bash(docker compose -f docker-compose.test.yml down*)",
+      "Bash(docker compose -f docker-compose.test.yml run*)"
+    ],
+    "deny": [
+      "Bash(rm -rf *)",
+      "Bash(rm -fr *)",
+      "Bash(git push*)",
+      "Bash(git push --force*)",
+      "Bash(git push -f*)",
+      "Bash(git reset --hard*)",
+      "Bash(git clean -fd*)",
+      "Bash(gh pr merge*)",
+      "Bash(gh repo delete*)",
+      "Bash(uv publish*)",
+      "Bash(npm publish*)",
+      "Bash(curl *)",
+      "Bash(wget *)",
+      "WebFetch"
+    ]
+  }
+}

cenote_core-0.1.0/.env.example

@@ -0,0 +1,3 @@
+# Copy to .env and fill in real values (never commit .env)
+VOYAGE_API_KEY=
+COHERE_API_KEY=

cenote_core-0.1.0/.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 3
+    groups:
+      python-dependencies:
+        patterns: ["*"]
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 3
+    groups:
+      github-actions:
+        patterns: ["*"]

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

@@ -0,0 +1,129 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-and-type:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install deps
+        run: uv sync --all-extras
+      - name: Ruff check
+        run: uv run ruff check .
+      - name: Ruff format check
+        run: uv run ruff format --check .
+      - name: Mypy
+        run: uv run mypy src/
+
+  security-audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: Install deps (locked)
+        run: uv sync --all-extras --locked
+      - name: Export locked deps for pip-audit (excluding cenote-core itself)
+        run: |
+          uv export --no-hashes --no-emit-project --format requirements-txt \
+            --output-file requirements.audit.txt
+      - name: Audit dependencies for known CVEs
+        run: uv tool run pip-audit --strict --requirement requirements.audit.txt
+
+  unit-tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install deps
+        run: uv sync --all-extras
+      - name: Run unit tests
+        run: uv run pytest -m "not integration" --cov=cenote --cov-report=xml
+      - name: Upload coverage artifact
+        if: always() && matrix.python-version == '3.12'
+        uses: actions/upload-artifact@v7
+        with:
+          name: coverage
+          path: coverage.xml
+      - name: Upload coverage to Codecov
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.xml
+          flags: unit
+          fail_ci_if_error: false
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+  integration-tests:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: pgvector/pgvector:pg16
+        env:
+          POSTGRES_USER: cenote
+          POSTGRES_PASSWORD: cenote
+          POSTGRES_DB: cenote_test
+        ports:
+          - 5433:5432
+        options: >-
+          --health-cmd "pg_isready -U cenote -d cenote_test"
+          --health-interval 2s
+          --health-timeout 5s
+          --health-retries 30
+    env:
+      TEST_DATABASE_URL: postgresql://cenote:cenote@localhost:5433/cenote_test
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv python install 3.12
+      - run: uv sync --all-extras
+      - name: Wait for Postgres
+        run: |
+          for i in {1..30}; do
+            if pg_isready -h localhost -p 5433 -U cenote; then exit 0; fi
+            sleep 1
+          done
+          exit 1
+      - name: Run integration tests with coverage
+        run: uv run pytest -m integration --cov=cenote --cov-report=xml
+      - name: Upload integration coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.xml
+          flags: integration
+          fail_ci_if_error: false
+          token: ${{ secrets.CODECOV_TOKEN }}

cenote_core-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,39 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v6
+      - name: Setup Pages (auto-enable if not configured)
+        uses: actions/configure-pages@v5
+        with:
+          enablement: true
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv python install 3.12
+      - run: uv sync --all-extras
+      - run: uv run mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+      - id: deployment
+        uses: actions/deploy-pages@v4

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

@@ -0,0 +1,35 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/cenote-core
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv python install 3.12
+      - run: uv sync --all-extras
+      - name: Build wheel + sdist
+        run: uv build
+      - name: Verify build in isolated venv
+        run: |
+          uv venv /tmp/verify
+          uv pip install --python /tmp/verify/bin/python dist/cenote_core-*.whl
+          /tmp/verify/bin/python -c "import cenote; print(cenote.__version__)"
+      - name: Publish to PyPI via Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

cenote_core-0.1.0/.gitignore

@@ -0,0 +1,62 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+
+# Type checking
+.mypy_cache/
+.pyright/
+
+# Ruff
+.ruff_cache/
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Claude Code local overrides (not the shared settings.json)
+.claude/settings.local.json
+.claude/cache/
+
+# Internal brainstorming specs (ephemeral artifacts; plans under docs/superpowers/plans/ remain tracked)
+docs/superpowers/
+
+# Docker volumes (test pgvector data)
+.docker-volumes/
+
+# mkdocs build output
+/site/

cenote_core-0.1.0/.markdownlint.json

@@ -0,0 +1,7 @@
+{
+  "default": true,
+  "MD013": false,
+  "MD024": { "siblings_only": true },
+  "MD033": false,
+  "MD041": false
+}

cenote_core-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,26 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: ["--maxkb=500"]
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.14
+    hooks:
+      - id: ruff
+        args: ["--fix"]
+      - id: ruff-format
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        language: system
+        entry: uv run mypy
+        files: ^src/
+        pass_filenames: false
+        args: ["src/"]

cenote_core-0.1.0/CHANGELOG.md

@@ -0,0 +1,132 @@
+# Changelog
+
+All notable changes to this project will be documented here.
+
+Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/).
+Versioning: [SemVer 2.0.0](https://semver.org/spec/v2.0.0.html).
+
+> **Pre-1.0 disclaimer.** APIs may break in any minor release until `1.0.0` ships.
+> Patch releases (`0.1.0` → `0.1.1`) are bug fixes only.
+
+## [Unreleased]
+
+### Added
+
+- (none yet)
+
+## [0.1.0] - 2026-05-25
+
+### Added
+
+- PyPI package name: `cenote-core` (aligns with `langchain-core`,
+  `llama-index-core`, `pydantic-core` ecosystem patterns). Import remains
+  `import cenote` (Pillow/scikit-learn precedent — distribution name and
+  import name need not match).
+- GitHub repo renamed `pycenote` → `cenote` (brand umbrella; GitHub
+  auto-redirects old URLs).
+- `CONTRIBUTING.md` with dev setup, test commands, code style, commit
+  conventions, and the release process via PyPI Trusted Publishing.
+- Full README rewrite with new positioning ("not a LangChain alternative —
+  production minimalist for teams that hit framework complexity ceilings"),
+  module status table split into M1.0 / M1.1+ columns, expanded quickstart,
+  extension example with structural-typing pattern, architecture section
+  with diagram links, and roadmap with realistic M1.0/M1.1/M1.2+ scope.
+- GitHub Actions release workflow with PyPI OIDC trusted publishing.
+  Triggers on `v*` tag push and publishes to <https://pypi.org/project/cenote-core/>.
+  Requires one-time setup on PyPI to register the pending publisher.
+- Cookbook: `examples/custom_embedder.py` (structural-typing demo — implement
+  the `Embedder` protocol without inheritance) and `examples/pgvector_setup.py`
+  (production PgVectorStore — connect with retry, apply migrations,
+  multi-tenant indexing, namespace isolation verification).
+- `examples` added to ruff src list.
+- Documentation site powered by `mkdocs-material` and `mkdocstrings-python`.
+  Deployed to GitHub Pages at <https://jovandyaz.github.io/cenote/> via
+  GitHub Actions on every push to main. Includes auto-generated API
+  reference, quickstart, architecture page linking to drawio diagrams, and
+  extension tutorials for custom embedders and chunkers.
+- `mkdocs-material`, `mkdocstrings-python` added as dev dependencies.
+- Docs badge added to README. Diagrams link directly to GitHub's native
+  drawio renderer (no PNG exports needed).
+- PgVectorStore unit-level test coverage raised from 21% to ≥80% via
+  `tests/stores/test_pgvector_helpers.py` (pure helpers, no Postgres
+  dependency). Integration tests continue to cover the database layer.
+- Codecov integration: CI uploads `coverage.xml` to Codecov on every push
+  to main; coverage badge added to README. Requires `CODECOV_TOKEN` secret.
+- Structured logging via `logging.getLogger(__name__)` in every non-trivial
+  module under `src/cenote/`. Key events emit at DEBUG; transient failures
+  (retries, rate-limit waits) emit at WARNING. No `print()` calls remain.
+- `cenote.types` module with public type aliases (`Vector`, `Namespace`,
+  `ModelId`, `ContentHash`). Adopted in public signatures of `Embedder`,
+  `EmbeddingCache`, `VectorStore`.
+- `cenote.errors` exception hierarchy: `CenoteError`, `ConfigurationError`,
+  `EmbeddingError`, `RateLimitError`, `VectorStoreError`, `DimensionMismatchError`,
+  `MigrationError`. Replaces bare `ValueError` raises throughout `src/cenote/`.
+- `cenote.models`: `Document`, `Chunk`, `EmbeddedChunk`, `RetrievalResult`
+  Pydantic v2 models with `extra="forbid"`. `Chunk.make_id(doc_id, pos)`
+  produces deterministic chunk IDs.
+- `cenote.chunkers`: `Chunker` Protocol (with `chunk.content` contract docstring)
+  and `RecursiveCharacterChunker` (priority-list separators, configurable
+  `chunk_size=512` and `chunk_overlap=50`, deep-copied metadata, unicode-safe).
+- `cenote.embedders`: `Embedder` Protocol (`model_id`, `dimensions`, async
+  `embed`/`embed_query`) and `MockEmbedder` (deterministic unit-norm vectors
+  derived from content hash; matches real-embedder distribution to surface
+  ranking bugs that raw Gaussian vectors would hide).
+- `cenote.embedders.cache`: `EmbeddingCache` Protocol, `InMemoryCache`
+  (dict-backed, copies on `set` to avoid poisoning), and `CachedEmbedder`
+  wrapper (slot-array preserves input order; only cache misses hit the
+  inner embedder; cache key is `(model_id, content_hash)` so different
+  models do not collide).
+- `cenote.embedders.voyage.VoyageEmbedder` and
+  `cenote.embedders.cohere.CohereEmbedder`: production-grade multilingual
+  embedders over Voyage AI and Cohere v2 REST APIs. Both ship with input
+  batching (Voyage ≤128/req, Cohere ≤96/req), concurrency caps via
+  `asyncio.Semaphore`, exponential-backoff retries on 429/5xx, and an
+  optional sliding-window RPM rate limiter.
+- `cenote.embedders._http`: shared `RateLimiter` (sliding window, lock-coordinated
+  across tasks) and `retrying(...)` helper.
+- Runtime dep: `httpx>=0.27`. Dev dep: `respx>=0.21` (HTTP mocking — no real
+  API calls in CI).
+- `.env.example`: template for `VOYAGE_API_KEY`, `COHERE_API_KEY`.
+- `cenote.stores`: `VectorStore` Protocol (multi-tenant, `namespace` mandatory
+  on every method) and `InMemoryVectorStore` (numpy-backed cosine similarity,
+  per-namespace dicts, optional metadata-filter via exact JSONB-style match).
+  Production-grade backend (PgVectorStore) lands in a later task.
+- Runtime dep: `numpy>=2.0`.
+- `cenote.retrievers`: `Retriever` Protocol and `VectorRetriever` (composes
+  any `Embedder` with any `VectorStore`; embeds the query, searches the store,
+  normalizes `retriever="vector"` on every `RetrievalResult`).
+- `cenote.stores.PgVectorStore`: production-grade `VectorStore` backed by
+  Postgres + pgvector. Hardenings: transactional `upsert`/`delete`,
+  idempotent migrations tracking (`cenote_schema_migrations` table),
+  exponential-backoff `connect()` retry on container-not-ready races,
+  pre-flight dimension validation, configurable HNSW `m` /
+  `ef_construction` (migration template) and runtime `ef_search`. Initial
+  schema in `001_init.sql` ships a GIN index on `metadata` so `@>` filters
+  are O(log n) instead of seq-scan.
+- `docker-compose.test.yml`: `pgvector/pgvector:pg16` container on port 5433
+  for local integration tests.
+- CI: new `integration-tests` job spins up a Postgres service container,
+  exports `TEST_DATABASE_URL`, and runs `pytest -m integration`.
+- Runtime dep: `asyncpg>=0.30`. Dev dep: `asyncpg-stubs>=0.31.2` (types).
+- `demos/quickstart.py`: end-to-end demo CLI — indexes a small EN corpus
+  (`demos/data/wikipedia_snippets.json`, 20 entries) through chunker +
+  embedder + in-memory store, then runs sample queries against
+  `VectorRetriever`. `--provider {mock,voyage,cohere}` toggles between the
+  no-API mock and the real multilingual embedders. Smoke test
+  (`tests/demos/test_quickstart_smoke.py`) runs the mock path on every CI.
+- README: added `## Quickstart` section with the three provider invocations
+  and softened the "LATAM-rooted" claim to match what M1.0 actually ships
+  (multilingual embedders today; Spanish-specific BM25 + ES eval datasets
+  on the M1.1+ roadmap).
+- `cenote.rerankers.Reranker` Protocol (no impl yet — concrete
+  `VoyageReranker` / `CohereReranker` ship in M1.1).
+- `cenote.observability`: `Tracer` Protocol + `NoopTracer` default. OTel and
+  Langfuse adapters land in M1.1 without breaking the API.
+- `cenote.eval.metrics`: BEIR-style retrieval quality helpers —
+  `precision_at_k`, `recall_at_k`, `mean_reciprocal_rank`. DeepEval
+  integration arrives in M1.1.
+- Initial project scaffolding: `uv`, `ruff`, `mypy --strict`, `pytest`, `pre-commit`,
+  GitHub Actions CI (lint + type + unit tests, Python 3.12 & 3.13, `pip-audit`).
+- `LICENSE` (Apache 2.0), `CHANGELOG.md`, `SECURITY.md`.
+- `py.typed` marker — package ships type information to consumers (PEP 561).
+- `__version__` exposed via `importlib.metadata` (single source of truth).

cenote_core-0.1.0/CLAUDE.md

@@ -0,0 +1,145 @@
+# CLAUDE.md
+
+This file is the persistent context for Claude Code sessions working on `cenote`. Read it at the start of every session.
+
+## What this project is
+
+`cenote` is a production-grade Python framework for building agentic RAG applications, with first-class support for Spanish-language content and Latin American use cases. It is the **shared core** for two downstream products that live in separate repos:
+
+- **knowtis-ai** — RAG and research agent over the Knowtis notes platform
+- **cfdi-agent** — accounting reconciliation + CFDI 4.0 compliance agent for Mexican PYMEs
+
+Each downstream product validates the core from opposite ends: knowtis-ai needs creative synthesis, cfdi-agent needs deterministic correctness with audit trails. If the core serves both, it serves most production RAG verticals.
+
+This repo (`cenote`) contains the core library only. PyPI publication name is `cenote-core` — aligned with `langchain-core` / `llama-index-core` / `pydantic-core` patterns. Import remains `import cenote` (Pillow/scikit-learn precedent: distribution name and import name need not match). The bare `cenote` PyPI slot is held by an abandoned 2019 project; we do not pursue PEP 541 reclaim.
+
+## Tech stack
+
+- **Python**: 3.12+
+- **Package manager**: `uv` (use `uv sync`, `uv add`, `uv run ...`)
+- **Linting & formatting**: `ruff` (replaces black, isort, flake8)
+- **Type checking**: `mypy --strict`
+- **Testing**: `pytest` + `pytest-asyncio` + `pytest-cov`
+- **Data validation**: `pydantic` v2
+- **Async**: default; sync only when wrapping inherently sync libraries
+- **LLM provider**: Anthropic Claude (Sonnet 4.5 default, Opus for high-stakes reasoning)
+- **Agent framework**: LangGraph (for state machines with conditional edges)
+- **Vector store**: pgvector (Postgres extension)
+- **Embeddings**: provider-agnostic protocol; concrete impl deferred (Voyage AI vs Cohere multilingual decision pending)
+- **Observability**: Langfuse (self-hostable)
+- **Evaluation**: DeepEval + custom metrics
+
+## Project structure
+
+```
+cenote/  (repo root; on disk during dev, may be cloned as `cenote/` after the rename)
+├── src/cenote/
+│   ├── chunkers/      # Text/markdown splitting
+│   ├── embedders/     # Embedding providers (protocol + impls)
+│   ├── stores/        # Vector stores (protocol + impls)
+│   ├── retrievers/    # Retrieval strategies (BM25, vector, hybrid)
+│   ├── rerankers/     # (future) Reranking strategies
+│   ├── llm/           # (future) LLM client abstractions
+│   ├── agents/        # (future) Agent primitives over LangGraph
+│   ├── eval/          # (future) Eval harness
+│   ├── observability/ # (future) Tracing helpers
+│   ├── models.py      # Pydantic models (Document, Chunk, etc.)
+│   └── types.py       # Shared type aliases
+├── tests/             # Mirror src/cenote/ structure
+├── docs/              # Milestone briefs and design docs
+└── pyproject.toml
+```
+
+## Conventions
+
+### Code style
+
+- Type hints on everything public. `mypy --strict` must pass.
+- Pydantic models for any data crossing module boundaries.
+- Prefer `Protocol` over `ABC` for interfaces — duck typing + better composition.
+- One class per concept per file. Avoid mega-modules.
+- Async by default. Sync versions only where retrieval libraries force it.
+
+### License headers (SPDX)
+
+Every `.py` file in `src/` starts with:
+
+```python
+# SPDX-License-Identifier: Apache-2.0
+```
+
+It must be the **first non-empty line** (before the module docstring). Test files are exempt. Lint enforcement via `reuse-tool` is M1.1+; for now it's convention.
+
+### Naming
+
+- Files and modules: `snake_case`
+- Classes: `PascalCase`
+- Protocols: just use the bare noun (`Chunker`, `Embedder`). Suffix with `Protocol` only when there's ambiguity with a concrete impl in the same module.
+- Spanish identifiers are OK in domain-specific downstream code (`cfdi`, `rfc`, `iva`), never in this core repo.
+
+### Tests
+
+- One test file per source file. Mirror the path: `src/cenote/chunkers/markdown.py` ↔ `tests/chunkers/test_markdown.py`.
+- Shared setup goes in `tests/conftest.py` or per-directory `conftest.py`.
+- Integration tests (those requiring Postgres) go in `tests/integration/` and are marked `@pytest.mark.integration`.
+- Aim for >80% coverage on `src/cenote/`.
+
+### Commits
+
+- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `test:`, `refactor:`
+- Keep PRs focused. One sub-deliverable per PR (see `docs/00-first-milestone.md` for suggested breakdown).
+- Branch naming: `feat/<short-desc>`, `fix/<short-desc>`, etc.
+
+### Documentation
+
+- Public functions/classes need docstrings (Google style).
+- Module-level docstring explains the module's purpose in 1–2 lines.
+- Examples in docstrings should be runnable.
+
+## Commands
+
+```bash
+# Setup
+uv sync                              # install all deps (incl. dev)
+
+# Development
+uv run pytest                        # all tests
+uv run pytest tests/chunkers/        # subset
+uv run pytest -m "not integration"   # skip integration tests
+uv run pytest --cov=cenote           # with coverage
+uv run ruff check .                  # lint
+uv run ruff format .                 # format
+uv run mypy src/                     # type check
+uv run pre-commit run --all-files    # all checks
+
+# Adding deps
+uv add <package>                     # runtime dep
+uv add --dev <package>               # dev dep
+
+# Build
+uv build                             # build wheel
+```
+
+## What to NOT do
+
+- **Do not pull in LangChain** as a dependency. We use LangGraph (a focused subset) only. The LangChain mega-package is not wanted here.
+- **Do not add concrete embedder implementations yet**. The `Embedder` protocol must stabilize first; the Voyage vs Cohere decision is pending.
+- **Do not bake assumptions about Spanish-only**. The framework is LATAM-aware but multilingual. Default tokenizer/chunker choices must not be English-only.
+- **Do not add framework-specific code** (FastAPI, Django, Flask, etc.) to `cenote` core. Those belong in downstream services that depend on `cenote`.
+- **Do not commit secrets**. Use `.env` (gitignored) and `pydantic-settings`.
+- **Do not skip type hints or tests** for "I'll add them later". Add them in the same PR or don't add the code.
+- **Do not bypass the namespace parameter** on `VectorStore` / `Retriever` interfaces. Multi-tenancy is enforced at the protocol level.
+- **Do not edit migrations** once committed. Add a new migration instead.
+
+## Current focus
+
+See `docs/00-first-milestone.md` for the active milestone scope. As of project start, we are building **M1.0 — Core Primitives**: chunkers, embedders, stores, retrievers.
+
+Do NOT start work on agents, eval, or observability yet. Those depend on the primitives being stable.
+
+## When in doubt
+
+- Check `docs/` for design rationales
+- Check existing implementations in the same module for patterns
+- If introducing a new top-level dependency, propose it first (open a discussion or ask the maintainer)
+- The maintainer is Jovan Díaz ([@jovandyaz](https://github.com/jovandyaz))