dynamanic-raggedy 0.1.0a0__tar.gz

dynamanic_raggedy-0.1.0a0/.env.example

@@ -0,0 +1,22 @@
+# Copy to .env and uncomment any keys you want Raggedy to pick up.
+# `Raggedy()` calls python-dotenv at construction time and populates
+# os.environ (without overriding existing vars), so provider SDKs
+# (anthropic, openai) read these directly.
+
+# --- LLM providers ----------------------------------------------------
+# ANTHROPIC_API_KEY=
+# OPENAI_API_KEY=
+# OPENAI_ORG=
+# OLLAMA_HOST=http://localhost:11434
+# LMSTUDIO_BASE_URL=http://localhost:1234/v1
+# LMSTUDIO_API_KEY=lm-studio
+
+# --- Raggedy adapter selection (any RAGGEDY_* setting in config.py) ---
+# RAGGEDY_LLM=anthropic
+# RAGGEDY_LLM_MODEL=claude-haiku-4-5-20251001
+# RAGGEDY_EMBEDDING=sentence-transformers
+# RAGGEDY_EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
+# RAGGEDY_DEVICE=auto          # auto | cuda | mps | cpu
+# RAGGEDY_STORE=memory
+# RAGGEDY_NAMESPACE=default
+# RAGGEDY_COST_DAILY_LIMIT_USD=1.00

dynamanic_raggedy-0.1.0a0/.github/workflows/ci.yml

@@ -0,0 +1,119 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-and-type:
+    name: Lint + types (py3.12)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Ruff
+        run: python -m ruff check src tests examples
+      - name: Mypy
+        run: python -m mypy src
+
+  test:
+    name: pytest (py${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - name: Install base + dev
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Run tests (no coverage gate — adapter modules require extras)
+        run: python -m pytest -q --no-header
+
+  test-with-extras:
+    name: pytest + coverage (sqlite-vec + chroma + qdrant)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install extras
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,sqlitevec,chroma,qdrant]"
+      - name: Run tests with coverage gate
+        run: |
+          python -m pytest -q \
+            --cov=raggedy \
+            --cov-report=term-missing \
+            --cov-report=xml
+      - name: Upload coverage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-xml
+          path: coverage.xml
+
+  pgvector-integration:
+    name: pgvector integration
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: ankane/pgvector
+        env:
+          POSTGRES_PASSWORD: pg
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd="pg_isready -U postgres"
+          --health-interval=5s --health-timeout=5s --health-retries=10
+    env:
+      RAGGEDY_TEST_PG_URL: postgresql://postgres:pg@localhost:5432/postgres
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,pgvector]"
+      - name: pgvector tests
+        run: python -m pytest -q tests/stores/test_pgvector.py
+
+  docs-build:
+    name: docs build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[docs]"
+      - name: mkdocs build (strict)
+        run: python -m mkdocs build --strict

dynamanic_raggedy-0.1.0a0/.github/workflows/docs.yml

@@ -0,0 +1,43 @@
+name: Docs
+
+# Pages must be enabled in repo Settings → Pages (source: GitHub Actions)
+# before this workflow can deploy. Run manually via `gh workflow run docs.yml`
+# once Pages is set up; auto-deploy on push is intentionally disabled to
+# avoid red CI on repos where Pages isn't configured yet.
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    name: build & deploy
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[docs]"
+      - name: Build site
+        run: python -m mkdocs build --strict --site-dir _site
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+      - id: deployment
+        uses: actions/deploy-pages@v4

dynamanic_raggedy-0.1.0a0/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+.venv/
+.env
+.envrc
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+*.sqlite
+*.db
+.DS_Store
+.idea/
+.vscode/
+
+# mkdocs build output
+site/

dynamanic_raggedy-0.1.0a0/.python-version

@@ -0,0 +1 @@
+3.11

dynamanic_raggedy-0.1.0a0/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to Raggedy are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-05-19
+
+Initial alpha release.
+
+### Added
+
+#### Core pipeline
+- `Raggedy` facade and `RAGPipeline` async orchestrator (14-step flow: validate → start run → cost-gate → PII-redact → embed → retrieve → re-redact → pack → render prompt → LLM → record usage → finish run → return).
+- Eight Protocols for full adapter swappability: `VectorStore`, `EmbeddingBackend`, `LLMProvider`, `Chunker`, `PIIRedactor`, `CostTracker`, `RunRecorder`, `Logger`/`EventSink`.
+- Domain-neutral isolation: single `namespace: str` plus free-form `tags: dict[str, str]`. No tenant / matter / legal-specific concepts.
+- `RaggedyConfig` (pydantic-settings) with `RAGGEDY_*` env prefix, `.env` auto-load via python-dotenv, and `from_yaml(path)` loader.
+
+#### Vector stores
+- `InMemoryStore` — numpy cosine, namespace + tag filter.
+- `SqliteVecStore` (`[sqlitevec]`) — `sqlite-vec` extension, `distance_metric=cosine`, in-memory and file-backed.
+- `PgVectorStore` (`[pgvector]`) — asyncpg + pgvector; JSONB tags with GIN index.
+- `QdrantStore` (`[qdrant]`) — UUIDv5 from chunk id; supports embedded `:memory:` and HTTP/HTTPS endpoints.
+- `ChromaStore` (`[chroma]`) — EphemeralClient / PersistentClient / HttpClient; primitive metadata flattening.
+- `WeaviateStore` (`[weaviate]`) — v4 async client; PascalCase collection.
+
+#### LLM providers
+- `AnthropicProvider` (`[anthropic]`) — Claude 4.x family.
+- `OpenAIProvider` (`[openai]`) — tiktoken-aware `count_tokens` when installed.
+- `OllamaProvider` — uses base httpx; local zero-cost.
+- LM Studio dispatched through `OpenAIProvider` against `LMSTUDIO_BASE_URL`.
+
+#### Embedding backends
+- `DeterministicEmbedder` — hashed bag-of-words (real algorithm, useful for tests).
+- `SentenceTransformersEmbedder` (`[local]`) — GPU-aware via `detect_device()` (CUDA → MPS → CPU); honours `embedding_batch_size`.
+- `OpenAIEmbedder` (`[openai]`).
+- `OllamaEmbedder` — uses base httpx; batch `/api/embed` with single-shot fallback.
+
+#### Chunkers
+- `SemanticChunker` — paragraph + sentence boundaries, greedy merge, leading overlap, char-offset tracking.
+- `ParagraphChunker` — one chunk per paragraph.
+- `SentenceChunker` — sentence-level greedy merge.
+- `FixedChunker` — fixed-window with word-boundary snap.
+
+#### Intake layer
+- Sources: `MemorySource`, `FileSource`, `DirectorySource`, `UrlSource` (base), `S3Source` (`[s3]`).
+- Extractors: `PlainTextExtractor`, `HtmlExtractor` (stdlib only), `PdfExtractor` (`[pdf]`), `DocxExtractor` (`[docx]`).
+- `IntakeRunner` orchestrates source → extractor → `Document`. `ExtractorRegistry` dispatches by `content_type`.
+- `Raggedy.ingest_from(source)` one-liner with batching.
+
+#### Batteries
+- `RegexPIIRedactor` — 10 PII types (SSN, email, phone, DOB, address, credit-card with Luhn, IP, passport, driver's license, bank account). `RedactionResult.redaction_map` is in-memory only; never persisted.
+- `InMemoryCostTracker` and `SqliteCostTracker` (atomic daily upsert via `INSERT … ON CONFLICT DO UPDATE`).
+- `InMemoryRunRecorder` (bounded deque) and `SqliteRunRecorder` (FK-cascade artifacts, durable).
+- Versioned RAG prompt templates pinned in every run record (`prompt_template_version`).
+
+#### Tests, examples, docs
+- 73+ tests; full-suite tests run offline; pgvector / Weaviate / live-LLM tests skip-if-unavailable.
+- 6 worked examples (hello world, pgvector + Anthropic, local Ollama, custom chunker, intake directory, LM Studio GPU).
+- mkdocs-material site (`docs/`).
+
+### Design constraints
+- No mock LLM providers ship with the library; tests use real providers with skip-if-unavailable.
+- Async-first; sync shims via `asgiref.async_to_sync`.
+- All external calls wrapped → `ProviderError` / `ConfigError`. Run record always finalises with the appropriate status on every code path.

dynamanic_raggedy-0.1.0a0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dynamanic LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dynamanic_raggedy-0.1.0a0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: dynamanic-raggedy
+Version: 0.1.0a0
+Summary: Batteries-included, importable RAG core.
+Project-URL: Homepage, https://github.com/Dynamanic/raggedy
+Project-URL: Repository, https://github.com/Dynamanic/raggedy
+Author-email: Mike Jackson <dynamanicllc@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: embeddings,llm,rag,retrieval,vector-search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: asgiref>=3.8
+Requires-Dist: httpx>=0.27
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic-settings>=2.3
+Requires-Dist: pydantic>=2.7
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: python-ulid>=2.7
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: all
+Requires-Dist: aiosqlite>=0.20; extra == 'all'
+Requires-Dist: anthropic>=0.34; extra == 'all'
+Requires-Dist: asyncpg>=0.29; extra == 'all'
+Requires-Dist: boto3>=1.34; extra == 'all'
+Requires-Dist: chromadb>=0.5; extra == 'all'
+Requires-Dist: openai>=1.40; extra == 'all'
+Requires-Dist: pgvector>=0.3; extra == 'all'
+Requires-Dist: pypdf>=4.0; extra == 'all'
+Requires-Dist: python-docx>=1.1; extra == 'all'
+Requires-Dist: qdrant-client>=1.10; extra == 'all'
+Requires-Dist: sentence-transformers>=3.0; extra == 'all'
+Requires-Dist: sqlite-vec>=0.1.3; extra == 'all'
+Requires-Dist: torch>=2.2; extra == 'all'
+Requires-Dist: weaviate-client>=4.6; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.34; extra == 'anthropic'
+Provides-Extra: chroma
+Requires-Dist: chromadb>=0.5; extra == 'chroma'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: pymdown-extensions>=10; extra == 'docs'
+Provides-Extra: docx
+Requires-Dist: python-docx>=1.1; extra == 'docx'
+Provides-Extra: local
+Requires-Dist: sentence-transformers>=3.0; extra == 'local'
+Requires-Dist: torch>=2.2; extra == 'local'
+Provides-Extra: ollama
+Provides-Extra: openai
+Requires-Dist: openai>=1.40; extra == 'openai'
+Provides-Extra: pdf
+Requires-Dist: pypdf>=4.0; extra == 'pdf'
+Provides-Extra: pgvector
+Requires-Dist: asyncpg>=0.29; extra == 'pgvector'
+Requires-Dist: pgvector>=0.3; extra == 'pgvector'
+Provides-Extra: qdrant
+Requires-Dist: qdrant-client>=1.10; extra == 'qdrant'
+Provides-Extra: s3
+Requires-Dist: boto3>=1.34; extra == 's3'
+Provides-Extra: sqlitevec
+Requires-Dist: aiosqlite>=0.20; extra == 'sqlitevec'
+Requires-Dist: sqlite-vec>=0.1.3; extra == 'sqlitevec'
+Provides-Extra: weaviate
+Requires-Dist: weaviate-client>=4.6; extra == 'weaviate'
+Description-Content-Type: text/markdown
+
+# Raggedy
+
+Batteries-included, importable RAG core. `pip install dynamanic-raggedy`, then `from raggedy import ...` — drop it into any Python app.
+
+## Status
+
+Pre-release (`0.1.0a0`). The library ships no mock providers — every LLM and embedder is a real adapter. Tests skip cleanly when no live LLM is reachable.
+
+Phase 1 + intake + real providers shipped: in-memory store, deterministic embedder, semantic chunker, PII redaction (10 types, ephemeral map), cost tracking with daily limits, audit-run records, intake layer (files / directories / URLs / S3 → plain text / markdown / HTML / PDF / DOCX), and LLM adapters for Anthropic, OpenAI, Ollama, and LM Studio plus a GPU-aware local embedder (sentence-transformers, CUDA → MPS → CPU autodetect).
+
+## Quick start
+
+```python
+from raggedy import Raggedy, RaggedyConfig, Document
+
+rag = Raggedy(RaggedyConfig(
+    llm="anthropic",                  # or "openai", "ollama", "lm_studio"
+    llm_model="claude-haiku-4-5-20251001",
+    embedding="sentence-transformers",
+    embedding_model="sentence-transformers/all-MiniLM-L6-v2",
+    device="auto",                    # CUDA → MPS → CPU
+    store="memory",
+    namespace="kb-handbook",
+))
+
+rag.ingest_sync([
+    Document(id="hb-1", text="Refunds are processed within 5 business days."),
+])
+
+result = rag.query_sync("How long do refunds take?", top_k=4)
+print(result.answer)
+for s in result.sources:
+    print(f"[Source {s.index}] {s.document_id} score={s.score:.3f}")
+print(f"cost=${result.cost_usd:.6f} run_id={result.run_id}")
+```
+
+### `.env`
+
+`Raggedy()` calls `python-dotenv` once at construction and populates `os.environ` (without overriding existing vars). Drop your keys in a `.env` file at the project root:
+
+```
+ANTHROPIC_API_KEY=sk-ant-...
+OPENAI_API_KEY=sk-...
+OLLAMA_HOST=http://localhost:11434
+LMSTUDIO_BASE_URL=http://localhost:1234/v1
+```
+
+See `.env.example` for the full list.
+
+### Intake
+
+`Raggedy.ingest_from(source)` streams documents through extractors before indexing.
+
+```python
+from raggedy.intake import DirectorySource, UrlSource
+
+rag.ingest_from_sync(DirectorySource("./docs"), tags={"corpus": "handbook"})
+rag.ingest_from_sync(UrlSource(["https://example.com/blog"]))
+```
+
+## Install
+
+The PyPI distribution name is `dynamanic-raggedy` (the short name `raggedy` is taken by an unrelated maintained project). The import path is still `raggedy`.
+
+```sh
+pip install dynamanic-raggedy                  # base: deterministic embedder, in-memory store, intake stdlib parsers
+pip install "dynamanic-raggedy[anthropic]"     # Anthropic LLM
+pip install "dynamanic-raggedy[openai]"        # OpenAI LLM + embeddings; also powers LM Studio (OpenAI-compatible)
+pip install "dynamanic-raggedy[ollama]"        # no extra deps — ollama uses base httpx
+pip install "dynamanic-raggedy[local]"         # sentence-transformers + torch (GPU-aware)
+pip install "dynamanic-raggedy[pdf]"           # PDF extractor (pypdf)
+pip install "dynamanic-raggedy[docx]"          # DOCX extractor (python-docx)
+pip install "dynamanic-raggedy[s3]"            # S3 source (boto3)
+pip install "dynamanic-raggedy[sqlitevec]"     # SQLite-vec store
+pip install "dynamanic-raggedy[pgvector]"      # pgvector store
+pip install "dynamanic-raggedy[qdrant]"        # Qdrant store
+pip install "dynamanic-raggedy[chroma]"        # Chroma store
+pip install "dynamanic-raggedy[weaviate]"      # Weaviate store
+pip install "dynamanic-raggedy[all]"           # everything
+```
+
+## License
+
+MIT

dynamanic_raggedy-0.1.0a0/README.md

@@ -0,0 +1,84 @@
+# Raggedy
+
+Batteries-included, importable RAG core. `pip install dynamanic-raggedy`, then `from raggedy import ...` — drop it into any Python app.
+
+## Status
+
+Pre-release (`0.1.0a0`). The library ships no mock providers — every LLM and embedder is a real adapter. Tests skip cleanly when no live LLM is reachable.
+
+Phase 1 + intake + real providers shipped: in-memory store, deterministic embedder, semantic chunker, PII redaction (10 types, ephemeral map), cost tracking with daily limits, audit-run records, intake layer (files / directories / URLs / S3 → plain text / markdown / HTML / PDF / DOCX), and LLM adapters for Anthropic, OpenAI, Ollama, and LM Studio plus a GPU-aware local embedder (sentence-transformers, CUDA → MPS → CPU autodetect).
+
+## Quick start
+
+```python
+from raggedy import Raggedy, RaggedyConfig, Document
+
+rag = Raggedy(RaggedyConfig(
+    llm="anthropic",                  # or "openai", "ollama", "lm_studio"
+    llm_model="claude-haiku-4-5-20251001",
+    embedding="sentence-transformers",
+    embedding_model="sentence-transformers/all-MiniLM-L6-v2",
+    device="auto",                    # CUDA → MPS → CPU
+    store="memory",
+    namespace="kb-handbook",
+))
+
+rag.ingest_sync([
+    Document(id="hb-1", text="Refunds are processed within 5 business days."),
+])
+
+result = rag.query_sync("How long do refunds take?", top_k=4)
+print(result.answer)
+for s in result.sources:
+    print(f"[Source {s.index}] {s.document_id} score={s.score:.3f}")
+print(f"cost=${result.cost_usd:.6f} run_id={result.run_id}")
+```
+
+### `.env`
+
+`Raggedy()` calls `python-dotenv` once at construction and populates `os.environ` (without overriding existing vars). Drop your keys in a `.env` file at the project root:
+
+```
+ANTHROPIC_API_KEY=sk-ant-...
+OPENAI_API_KEY=sk-...
+OLLAMA_HOST=http://localhost:11434
+LMSTUDIO_BASE_URL=http://localhost:1234/v1
+```
+
+See `.env.example` for the full list.
+
+### Intake
+
+`Raggedy.ingest_from(source)` streams documents through extractors before indexing.
+
+```python
+from raggedy.intake import DirectorySource, UrlSource
+
+rag.ingest_from_sync(DirectorySource("./docs"), tags={"corpus": "handbook"})
+rag.ingest_from_sync(UrlSource(["https://example.com/blog"]))
+```
+
+## Install
+
+The PyPI distribution name is `dynamanic-raggedy` (the short name `raggedy` is taken by an unrelated maintained project). The import path is still `raggedy`.
+
+```sh
+pip install dynamanic-raggedy                  # base: deterministic embedder, in-memory store, intake stdlib parsers
+pip install "dynamanic-raggedy[anthropic]"     # Anthropic LLM
+pip install "dynamanic-raggedy[openai]"        # OpenAI LLM + embeddings; also powers LM Studio (OpenAI-compatible)
+pip install "dynamanic-raggedy[ollama]"        # no extra deps — ollama uses base httpx
+pip install "dynamanic-raggedy[local]"         # sentence-transformers + torch (GPU-aware)
+pip install "dynamanic-raggedy[pdf]"           # PDF extractor (pypdf)
+pip install "dynamanic-raggedy[docx]"          # DOCX extractor (python-docx)
+pip install "dynamanic-raggedy[s3]"            # S3 source (boto3)
+pip install "dynamanic-raggedy[sqlitevec]"     # SQLite-vec store
+pip install "dynamanic-raggedy[pgvector]"      # pgvector store
+pip install "dynamanic-raggedy[qdrant]"        # Qdrant store
+pip install "dynamanic-raggedy[chroma]"        # Chroma store
+pip install "dynamanic-raggedy[weaviate]"      # Weaviate store
+pip install "dynamanic-raggedy[all]"           # everything
+```
+
+## License
+
+MIT

dynamanic_raggedy-0.1.0a0/docs/adapters.md

@@ -0,0 +1,61 @@
+# Adapters
+
+Every adapter is loaded lazily by name through `RaggedyConfig`. Missing extras surface as `ConfigError` with the exact `pip install` command — never a raw `ImportError`.
+
+## Vector stores
+
+| `store=` | Module | Extra | URL form | Notes |
+|----------|--------|-------|----------|-------|
+| `memory`     | `raggedy.stores.memory.InMemoryStore`     | — (numpy only)         | n/a                              | Default. Dict + numpy cosine. |
+| `sqlite-vec` | `raggedy.stores.sqlite_vec.SqliteVecStore`| `[sqlitevec]`          | `:memory:` / file path / `sqlite:///…` | Local persistent. vec0 with `distance_metric=cosine`. |
+| `pgvector`   | `raggedy.stores.pgvector.PgVectorStore`   | `[pgvector]`           | `postgresql://…`                 | JSONB tags + GIN index. |
+| `qdrant`     | `raggedy.stores.qdrant.QdrantStore`       | `[qdrant]`             | `:memory:` / file path / `http(s)://…` | UUIDv5 from chunk id; one collection per Raggedy instance. |
+| `chroma`     | `raggedy.stores.chroma.ChromaStore`       | `[chroma]`             | `:memory:` / file path / `http(s)://…` | `embedding_function=None`; tags flattened to `tag_*` keys. |
+| `weaviate`   | `raggedy.stores.weaviate.WeaviateStore`   | `[weaviate]`           | `http(s)://…`                    | v4 async client; PascalCase collection. |
+
+Shared behaviour:
+
+- Cosine similarity throughout. Score = `1 - cosine_distance`.
+- Schema lazy-created on first `upsert` so the embedding dimension is known. Subsequent upserts with a different dim raise `ProviderError`.
+- Every adapter exposes `aclose()` to release pooled connections.
+
+## LLM providers
+
+| `llm=` | Module | Extra | Notes |
+|--------|--------|-------|-------|
+| `anthropic`           | `raggedy.llm.anthropic.AnthropicProvider` | `[anthropic]`           | Claude 4.x family. Reads `ANTHROPIC_API_KEY`. |
+| `openai`              | `raggedy.llm.openai.OpenAIProvider`       | `[openai]`              | tiktoken-aware `count_tokens` when installed. |
+| `ollama`              | `raggedy.llm.ollama.OllamaProvider`       | — (base httpx)          | Local. `estimate_cost` always returns 0. |
+| `lm_studio` / `lmstudio` | `raggedy.llm.openai.OpenAIProvider`    | `[openai]`              | OpenAI-compatible endpoint; reads `LMSTUDIO_BASE_URL`, `LMSTUDIO_API_KEY`. |
+
+## Embedding backends
+
+| `embedding=` | Module | Extra | Notes |
+|--------------|--------|-------|-------|
+| `deterministic`        | `raggedy.embeddings.deterministic.DeterministicEmbedder` | —              | Hashed bag-of-words. Real algorithm, no semantics — good for tests/CI. |
+| `sentence-transformers` / `local` | `raggedy.embeddings.local.SentenceTransformersEmbedder` | `[local]` | GPU-aware. `device="auto"` picks CUDA → MPS → CPU. |
+| `openai`               | `raggedy.embeddings.openai.OpenAIEmbedder`               | `[openai]`     | `text-embedding-3-small` default; pass `dimensions=` to truncate. |
+| `ollama`               | `raggedy.embeddings.ollama.OllamaEmbedder`               | — (base httpx) | Uses `/api/embed` (batch); falls back to `/api/embeddings`. |
+| `lm_studio` / `lmstudio` | `raggedy.embeddings.openai.OpenAIEmbedder`             | `[openai]`     | Reuses the OpenAI client pointed at LM Studio. |
+
+## Chunkers
+
+| `chunker_strategy=` | Module | Notes |
+|---------------------|--------|-------|
+| `semantic`  | `raggedy.chunking.semantic.SemanticChunker`   | Default. Paragraph + sentence boundaries, greedy merge, leading overlap. |
+| `paragraph` | `raggedy.chunking.paragraph.ParagraphChunker` | One chunk per paragraph (no merging). |
+| `sentence`  | `raggedy.chunking.sentence.SentenceChunker`   | Sentence-level greedy merge to `target_tokens`. |
+| `fixed`     | `raggedy.chunking.fixed.FixedChunker`         | Fixed window with overlap; word-boundary snap. |
+
+For a custom chunker, write any object satisfying the `Chunker` protocol and pass `chunker=` to `Raggedy(...)`. See [example 04](https://github.com/Dynamanic/raggedy/blob/main/examples/04_custom_chunker.py).
+
+## Persistence
+
+| `recorder=` / `cost_backend=` | Module | Extra |
+|---|---|---|
+| `recorder=memory`           | `raggedy.recording.memory.InMemoryRunRecorder` | — |
+| `recorder=sqlite`           | `raggedy.recording.sqlite.SqliteRunRecorder`   | `[sqlitevec]` |
+| `cost_backend=memory`       | `raggedy.cost.tracker.InMemoryCostTracker`     | — |
+| `cost_backend=sqlite`       | `raggedy.cost.sqlite.SqliteCostTracker`        | `[sqlitevec]` |
+
+The `SqliteCostTracker` uses an atomic `INSERT … ON CONFLICT DO UPDATE` to keep concurrent writers correct without an app-level lock.