knowledge-grove 0.1.0__tar.gz

knowledge_grove-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 konradquam
+
+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.

knowledge_grove-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: knowledge-grove
+Version: 0.1.0
+Summary: A Postgres-backed knowledge schema and SDK for shared agent context
+License: MIT License
+        
+        Copyright (c) 2026 konradquam
+        
+        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.
+        
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: alembic>=1.13
+Requires-Dist: psycopg[binary]>=3.1
+Requires-Dist: pgvector>=0.2
+Requires-Dist: sentence_transformers
+Requires-Dist: mcp>=2.0
+Requires-Dist: sqlparse>=0.5
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: testcontainers[postgres]>=4.0; extra == "test"
+Dynamic: license-file
+
+# Knowledge Grove
+
+A Postgres-backed knowledge schema and SDK that lets agents — in one repo and across repos — store, discover, and act on shared context: document chunks, embeddings, exact-match tags, and a graph of links between them, including links out to executable tools.
+
+**Status:** Core schema, SDK, CLI, and MCP server are implemented and tested (real Postgres, not mocks). A few sections of the original design are still open — see [Implementation status](knowledge-grove-design.md#implementation-status) in the design doc for the precise list.
+
+## Design commitments
+
+- **Postgres is the only system of record.** Vector search (`pgvector`), full-text search, exact-match lookups, and the relationship graph all live in one transactional database.
+- **The schema is normalized.** Every relationship — a tag, a link, an access grant — is its own row in its own table.
+- **Access control is enforced by Postgres itself**, via row-level security tied to each agent's own database role. Each agent authenticates with its own role and credentials — never one shared service account.
+
+## Core data model
+
+Four tables carry the whole system: `documents` (one row per chunk, with content, a content hash for exact-match dedup, an embedding, and full-text search columns), `document_tags` (exact-match labels), `edges` (a generic relationship graph — next/prev, source, tool links, related, supersedes), and `document_access` (per-document read/write grants). A fifth, `retrieval_feedback`, logs how documents perform for a query, for later ranking-weight tuning.
+
+## Entry points
+
+Five ways to land in the graph, each catching a case the others miss: direct ID lookup, tag matching, ILIKE/trigram search, full-text search, and embedding similarity — fused via weighted Reciprocal Rank Fusion. (A bounded, personalized-PageRank walk over the edge graph to expand past those entrance nodes is designed but not yet implemented — see the status link above.)
+
+## Installation
+
+Not yet published to PyPI. Install from source:
+
+```bash
+git clone https://github.com/konradquam/knowledge-grove.git
+cd knowledge-grove
+pip install .          # or: pip install -e . for an editable install
+```
+
+Requires Python 3.11+ and a Postgres server with the `pgvector` and `pg_trgm` extensions available (the bootstrapping step below creates them for you if your connecting role has privilege to).
+
+## Quickstart
+
+**1. Stand up the schema.** Run once per database, using a role with `CREATE EXTENSION`/table-owner privileges — never the role an ordinary agent connects as, since table owners bypass row-level security by default.
+
+```bash
+export KNOWLEDGE_GROVE_DSN="postgresql+psycopg://admin_role:password@host:5432/dbname"
+knowledge-grove init-db
+```
+
+**2. Provision an agent.** Each agent gets its own Postgres role, added to the `shared_reader` group so it can read whatever's been shared into that group by default. Still using the admin DSN:
+
+```bash
+knowledge-grove create-agent-role my_agent
+# Role 'my_agent' created.
+# Agent DSN: postgresql+psycopg://my_agent:<generated-password>@host:5432/dbname
+```
+
+Save that returned DSN somewhere your agent can read it (an env var, a secrets manager — resolving the secret is your project's job, not this package's; see §15 of the design doc).
+
+**3. Use it.** Either point an MCP-capable agent at the server (below), ingest existing files from a shell, or call the SDK directly from Python.
+
+```bash
+export KNOWLEDGE_GROVE_DSN="postgresql+psycopg://my_agent:<password>@host:5432/dbname"
+knowledge-grove ingest README.md docs/notes.py
+```
+
+## CLI reference
+
+All commands read their connection string from `KNOWLEDGE_GROVE_DSN`.
+
+| Command | Purpose |
+|---|---|
+| `init-db` | Run the bundled Alembic migrations: creates the schema, indexes, and RLS policies. Needs an admin/setup role. |
+| `create-agent-role <name> [--password PW]` | Provision a new agent's Postgres role and `shared_reader` membership. Prompts for a password (hidden) if `--password` is omitted. Needs an admin/setup role. |
+| `ingest <files...> [--source-url URL...] [--content-type {markdown,python,sql}...] [--roles JSON] [-y]` | Chunk and add one or more files as documents. `--source-url`/`--content-type` are given once per file (positionally matched); each defaults respectively to the file's own name and a guess from its extension. Re-ingesting a file under the same `source_url` reconciles against what's already there (a no-op if unchanged, a full replace if not) rather than duplicating it — warns and asks for confirmation first unless `-y` is given. `--roles` is a JSON object (e.g. `'{"shared_reader": ["read"]}'`, the default) applied to every document ingested in the call. |
+
+## MCP server
+
+`knowledge_grove.mcp_server` exposes the SDK as MCP tools over stdio (the default transport). Run it directly, or point an MCP-capable client at it:
+
+```json
+{
+  "mcpServers": {
+    "knowledge-grove": {
+      "command": "/path/to/venv/bin/python",
+      "args": ["-m", "knowledge_grove.mcp_server"],
+      "env": { "KNOWLEDGE_GROVE_DSN": "postgresql+psycopg://my_agent:<password>@host:5432/dbname" }
+    }
+  }
+}
+```
+
+Each entry in a client's MCP config gets its own subprocess, so each agent identity that needs its own Postgres role should get its own entry with its own DSN — one running server process, one fixed identity for its lifetime; nothing multiplexes several agents through a single connection.
+
+Tools exposed:
+
+| Tool | Purpose |
+|---|---|
+| `gather_context` | Fused search across all four entry points; the default way to look for existing context. |
+| `add_document` | Add one already-written chunk. |
+| `add_sequential_documents` | Add several chunks in order, auto-linked with `prev` edges. |
+| `add_authored_chunks` | Add several chunks in order, plus arbitrary extra edges (to existing documents, to each other, or to a URL) in the same call. |
+| `get_by_id` | Fetch a document by id. |
+| `get_edges` | Outgoing edges from a document (one hop). |
+| `update_document` | Create a new revision of a document (old one kept, flagged deprecated, linked via `supersedes`). |
+| `add_tag` | Attach an exact-match tag. |
+| `add_edge` | Attach a relationship to another document or an external URL. |
+| `grant_access` / `revoke_access` | Manage a document's access grants. |
+| `log_feedback` | Record how a document performed for a query. |
+
+Every tool's full description (usage guidance, argument shapes, when to prefer one over another) is visible to any MCP client that lists tools, and is worth reading directly in `src/knowledge_grove/mcp_server.py` if you're integrating one.
+
+## Using the SDK directly
+
+Everything the MCP server exposes is a thin wrapper over `knowledge_grove.crud` and `knowledge_grove.search` — call those directly from Python for non-MCP integrations (e.g. a Temporal activity):
+
+```python
+from knowledge_grove.db import get_engine, get_session
+from knowledge_grove import crud, search
+
+engine = get_engine("postgresql+psycopg://my_agent:password@host:5432/dbname")
+session = get_session(engine)
+
+doc = crud.add_document(session, content="Retries should use exponential backoff.", owner_agent="my_agent")
+session.commit()
+
+hits = search.gather_context(session, query_text="how do retries work", pattern="retry")
+```
+
+## Design document
+
+See [knowledge-grove-design.md](knowledge-grove-design.md) for the full design rationale — auth model, ranking math, chunking strategy, bootstrapping, and the [Implementation status](knowledge-grove-design.md#implementation-status) section tracking what's built against what's still designed-but-open.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

knowledge_grove-0.1.0/README.md

@@ -0,0 +1,128 @@
+# Knowledge Grove
+
+A Postgres-backed knowledge schema and SDK that lets agents — in one repo and across repos — store, discover, and act on shared context: document chunks, embeddings, exact-match tags, and a graph of links between them, including links out to executable tools.
+
+**Status:** Core schema, SDK, CLI, and MCP server are implemented and tested (real Postgres, not mocks). A few sections of the original design are still open — see [Implementation status](knowledge-grove-design.md#implementation-status) in the design doc for the precise list.
+
+## Design commitments
+
+- **Postgres is the only system of record.** Vector search (`pgvector`), full-text search, exact-match lookups, and the relationship graph all live in one transactional database.
+- **The schema is normalized.** Every relationship — a tag, a link, an access grant — is its own row in its own table.
+- **Access control is enforced by Postgres itself**, via row-level security tied to each agent's own database role. Each agent authenticates with its own role and credentials — never one shared service account.
+
+## Core data model
+
+Four tables carry the whole system: `documents` (one row per chunk, with content, a content hash for exact-match dedup, an embedding, and full-text search columns), `document_tags` (exact-match labels), `edges` (a generic relationship graph — next/prev, source, tool links, related, supersedes), and `document_access` (per-document read/write grants). A fifth, `retrieval_feedback`, logs how documents perform for a query, for later ranking-weight tuning.
+
+## Entry points
+
+Five ways to land in the graph, each catching a case the others miss: direct ID lookup, tag matching, ILIKE/trigram search, full-text search, and embedding similarity — fused via weighted Reciprocal Rank Fusion. (A bounded, personalized-PageRank walk over the edge graph to expand past those entrance nodes is designed but not yet implemented — see the status link above.)
+
+## Installation
+
+Not yet published to PyPI. Install from source:
+
+```bash
+git clone https://github.com/konradquam/knowledge-grove.git
+cd knowledge-grove
+pip install .          # or: pip install -e . for an editable install
+```
+
+Requires Python 3.11+ and a Postgres server with the `pgvector` and `pg_trgm` extensions available (the bootstrapping step below creates them for you if your connecting role has privilege to).
+
+## Quickstart
+
+**1. Stand up the schema.** Run once per database, using a role with `CREATE EXTENSION`/table-owner privileges — never the role an ordinary agent connects as, since table owners bypass row-level security by default.
+
+```bash
+export KNOWLEDGE_GROVE_DSN="postgresql+psycopg://admin_role:password@host:5432/dbname"
+knowledge-grove init-db
+```
+
+**2. Provision an agent.** Each agent gets its own Postgres role, added to the `shared_reader` group so it can read whatever's been shared into that group by default. Still using the admin DSN:
+
+```bash
+knowledge-grove create-agent-role my_agent
+# Role 'my_agent' created.
+# Agent DSN: postgresql+psycopg://my_agent:<generated-password>@host:5432/dbname
+```
+
+Save that returned DSN somewhere your agent can read it (an env var, a secrets manager — resolving the secret is your project's job, not this package's; see §15 of the design doc).
+
+**3. Use it.** Either point an MCP-capable agent at the server (below), ingest existing files from a shell, or call the SDK directly from Python.
+
+```bash
+export KNOWLEDGE_GROVE_DSN="postgresql+psycopg://my_agent:<password>@host:5432/dbname"
+knowledge-grove ingest README.md docs/notes.py
+```
+
+## CLI reference
+
+All commands read their connection string from `KNOWLEDGE_GROVE_DSN`.
+
+| Command | Purpose |
+|---|---|
+| `init-db` | Run the bundled Alembic migrations: creates the schema, indexes, and RLS policies. Needs an admin/setup role. |
+| `create-agent-role <name> [--password PW]` | Provision a new agent's Postgres role and `shared_reader` membership. Prompts for a password (hidden) if `--password` is omitted. Needs an admin/setup role. |
+| `ingest <files...> [--source-url URL...] [--content-type {markdown,python,sql}...] [--roles JSON] [-y]` | Chunk and add one or more files as documents. `--source-url`/`--content-type` are given once per file (positionally matched); each defaults respectively to the file's own name and a guess from its extension. Re-ingesting a file under the same `source_url` reconciles against what's already there (a no-op if unchanged, a full replace if not) rather than duplicating it — warns and asks for confirmation first unless `-y` is given. `--roles` is a JSON object (e.g. `'{"shared_reader": ["read"]}'`, the default) applied to every document ingested in the call. |
+
+## MCP server
+
+`knowledge_grove.mcp_server` exposes the SDK as MCP tools over stdio (the default transport). Run it directly, or point an MCP-capable client at it:
+
+```json
+{
+  "mcpServers": {
+    "knowledge-grove": {
+      "command": "/path/to/venv/bin/python",
+      "args": ["-m", "knowledge_grove.mcp_server"],
+      "env": { "KNOWLEDGE_GROVE_DSN": "postgresql+psycopg://my_agent:<password>@host:5432/dbname" }
+    }
+  }
+}
+```
+
+Each entry in a client's MCP config gets its own subprocess, so each agent identity that needs its own Postgres role should get its own entry with its own DSN — one running server process, one fixed identity for its lifetime; nothing multiplexes several agents through a single connection.
+
+Tools exposed:
+
+| Tool | Purpose |
+|---|---|
+| `gather_context` | Fused search across all four entry points; the default way to look for existing context. |
+| `add_document` | Add one already-written chunk. |
+| `add_sequential_documents` | Add several chunks in order, auto-linked with `prev` edges. |
+| `add_authored_chunks` | Add several chunks in order, plus arbitrary extra edges (to existing documents, to each other, or to a URL) in the same call. |
+| `get_by_id` | Fetch a document by id. |
+| `get_edges` | Outgoing edges from a document (one hop). |
+| `update_document` | Create a new revision of a document (old one kept, flagged deprecated, linked via `supersedes`). |
+| `add_tag` | Attach an exact-match tag. |
+| `add_edge` | Attach a relationship to another document or an external URL. |
+| `grant_access` / `revoke_access` | Manage a document's access grants. |
+| `log_feedback` | Record how a document performed for a query. |
+
+Every tool's full description (usage guidance, argument shapes, when to prefer one over another) is visible to any MCP client that lists tools, and is worth reading directly in `src/knowledge_grove/mcp_server.py` if you're integrating one.
+
+## Using the SDK directly
+
+Everything the MCP server exposes is a thin wrapper over `knowledge_grove.crud` and `knowledge_grove.search` — call those directly from Python for non-MCP integrations (e.g. a Temporal activity):
+
+```python
+from knowledge_grove.db import get_engine, get_session
+from knowledge_grove import crud, search
+
+engine = get_engine("postgresql+psycopg://my_agent:password@host:5432/dbname")
+session = get_session(engine)
+
+doc = crud.add_document(session, content="Retries should use exponential backoff.", owner_agent="my_agent")
+session.commit()
+
+hits = search.gather_context(session, query_text="how do retries work", pattern="retry")
+```
+
+## Design document
+
+See [knowledge-grove-design.md](knowledge-grove-design.md) for the full design rationale — auth model, ranking math, chunking strategy, bootstrapping, and the [Implementation status](knowledge-grove-design.md#implementation-status) section tracking what's built against what's still designed-but-open.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

knowledge_grove-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "knowledge-grove"
+version = "0.1.0"
+description = "A Postgres-backed knowledge schema and SDK for shared agent context"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.11"
+dependencies = [
+    "sqlalchemy>=2.0",
+    "alembic>=1.13",
+    "psycopg[binary]>=3.1",
+    "pgvector>=0.2",
+    "sentence_transformers",
+    "mcp>=2.0",
+    "sqlparse>=0.5",
+]
+
+[project.scripts]
+knowledge-grove = "knowledge_grove.cli:main"
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0",
+    "testcontainers[postgres]>=4.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

knowledge_grove-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

knowledge_grove-0.1.0/src/knowledge_grove/__init__.py

@@ -0,0 +1,18 @@
+from knowledge_grove.db import get_engine, get_session
+from knowledge_grove.models import (
+    Document,
+    DocumentTag,
+    Edge,
+    DocumentAccess,
+    RetrievalFeedback,
+)
+
+__all__ = [
+    "get_engine",
+    "get_session",
+    "Document",
+    "DocumentTag",
+    "Edge",
+    "DocumentAccess",
+    "RetrievalFeedback",
+]

knowledge_grove-0.1.0/src/knowledge_grove/cli.py

@@ -0,0 +1,268 @@
+"""CLI commands: bootstrapping (`init-db`, `create-agent-role`, §14 of the
+design doc, ops-facing one-time-per-database/per-agent setup) and content
+ingestion (`ingest`, a thin wrapper over add_file_as_document/§13 dedup for
+use from a shell rather than another agent's own code).
+"""
+import argparse
+import getpass
+import json
+import os
+from pathlib import Path
+
+from alembic import command
+from alembic.config import Config
+from psycopg import sql
+from sqlalchemy import create_engine, func, select, text
+from sqlalchemy.engine import make_url
+
+import knowledge_grove
+from knowledge_grove.constants import ContentType, SHARED_READER
+from knowledge_grove.db import get_engine, get_session
+from knowledge_grove.models import Document
+from knowledge_grove.utils.input_output import add_file_as_document, detect_content_type
+
+
+def _alembic_config(dsn: str) -> Config:
+    """Build an Alembic Config pointing at this package's own bundled
+    migrations directly, rather than relying on alembic.ini being present on
+    disk -- that file lives at the repo root, outside the installed package,
+    so it won't exist for a real (non-editable) install of knowledge-grove
+    used from another project.
+    """
+    migrations_dir = Path(knowledge_grove.__file__).parent / "migrations"
+    cfg = Config()
+    cfg.set_main_option("script_location", str(migrations_dir))
+    cfg.set_main_option("sqlalchemy.url", dsn)
+    return cfg
+
+
+def init_db(dsn: str) -> None:
+    """Run every bundled migration up to head against `dsn`.
+
+    Must be run by a role with CREATE EXTENSION / CREATE POLICY / table-owner
+    privileges -- never the role an ordinary agent connects as, since table
+    owners bypass RLS by default (see the initial migration's own docstring).
+    """
+    command.upgrade(_alembic_config(dsn), "head")
+
+
+def create_agent_role(dsn: str, role_name: str, password: str) -> str:
+    """Provision a new agent's Postgres role: LOGIN credentials, the base
+    grants every agent needs, and membership in `shared_reader` so it can
+    read whatever's been shared into that group by default.
+
+    `dsn` must belong to a role with privileges to create roles and grant
+    table access (the same setup-only role `init_db` requires), not an
+    ordinary agent role. Returns the DSN the new agent should connect with.
+
+    Role names and the password can't be passed as ordinary bind parameters
+    -- CREATE ROLE / GRANT are utility statements, not DML, so Postgres
+    doesn't accept protocol-level placeholders for them. `psycopg.sql`
+    composes them safely instead (proper identifier quoting for the role
+    name, proper literal escaping for the password).
+    """
+    engine = create_engine(dsn)
+    try:
+        with engine.begin() as conn:
+            cur = conn.connection.dbapi_connection.cursor()
+            cur.execute(
+                sql.SQL("CREATE ROLE {} LOGIN PASSWORD {}").format(
+                    sql.Identifier(role_name), sql.Literal(password)
+                )
+            )
+            cur.execute(
+                sql.SQL(
+                    "GRANT SELECT, INSERT, UPDATE, DELETE ON "
+                    "documents, document_tags, edges, document_access TO {}"
+                ).format(sql.Identifier(role_name))
+            )
+            cur.execute(
+                sql.SQL("GRANT SELECT, INSERT ON retrieval_feedback TO {}").format(
+                    sql.Identifier(role_name)
+                )
+            )
+            cur.execute(
+                sql.SQL("GRANT {} TO {}").format(
+                    sql.Identifier(SHARED_READER), sql.Identifier(role_name)
+                )
+            )
+    finally:
+        engine.dispose()
+
+    agent_url = make_url(dsn).set(username=role_name, password=password)
+    return agent_url.render_as_string(hide_password=False)
+
+
+def _current_agent(session) -> str:
+    """The Postgres role this connection is actually authenticated as -- see
+    mcp_server.py's identical helper for why document ownership always comes
+    from the connection itself, never a caller-supplied argument.
+    """
+    return session.execute(text("SELECT current_user")).scalar()
+
+
+def _active_document_count(session, source_url: str) -> int:
+    return session.scalar(
+        select(func.count()).select_from(Document).where(
+            Document.source_url == source_url, Document.deprecated.is_(False)
+        )
+    )
+
+
+def ingest_files(
+    dsn: str,
+    file_paths: list[str],
+    source_urls: list[str | None] | None = None,
+    content_types: list[str | None] | None = None,
+    roles: dict[str, list[str]] | None = None,
+    assume_yes: bool = False,
+) -> None:
+    """Ingest one or more files as documents, chunking each and computing
+    embeddings (add_file_as_document). `dsn` should be an ordinary agent's
+    connection string, not the admin/setup one `init_db`/`create_agent_role`
+    need -- ownership is derived from whichever role `dsn` authenticates as.
+
+    Each file's `source_url` defaults to its own filename (not a real URL,
+    just a stable identifier re-ingesting the same file later will match
+    again -- see add_raw_document's §13 reconciliation). If a source_url
+    already has existing documents, this asks for confirmation before
+    proceeding (unless `assume_yes`): re-using an existing source_url for a
+    genuinely different file would make add_raw_document treat it as a
+    changed revision and deprecate that unrelated content.
+
+    Each file's `content_type` (which chunker to use) defaults to a guess
+    from its extension (detect_content_type) -- `.py` -> python, `.sql` ->
+    sql, everything else -> markdown. Pass `content_types` to override that
+    per file, matched by position to `file_paths`.
+
+    `roles` grants other roles access to every document ingested in this
+    call (see add_document); if omitted, defaults to {"shared_reader":
+    ["read"]} -- readable by every agent in the shared_reader group. Pass
+    {} to keep everything ingested here private to the owner only.
+    """
+    resolved_source_urls = [
+        source_urls[i] if source_urls and source_urls[i] else Path(file_paths[i]).name
+        for i in range(len(file_paths))
+    ]
+    resolved_content_types = [
+        content_types[i] if content_types else None
+        for i in range(len(file_paths))
+    ]
+
+    engine = get_engine(dsn)
+    session = get_session(engine)
+    try:
+        owner_agent = _current_agent(session)
+
+        for path, source_url, content_type in zip(file_paths, resolved_source_urls, resolved_content_types):
+            existing_count = _active_document_count(session, source_url)
+            if existing_count > 0 and not assume_yes:
+                print(
+                    f"Warning: {existing_count} existing document(s) already use "
+                    f"source_url '{source_url}'. Continuing will treat '{path}' as a "
+                    f"new revision of that same source: identical content is a "
+                    f"no-op, but different content will deprecate the existing "
+                    f"chunks. If '{path}' is not actually a revision of that source, "
+                    f"answer no and re-run with a different --source-url."
+                )
+                answer = input("Proceed? [y/N] ").strip().lower()
+                if answer != "y":
+                    print(f"Skipped '{path}'.")
+                    continue
+
+            docs = add_file_as_document(
+                session, path, owner_agent=owner_agent, source_url=source_url,
+                content_type=content_type, roles=roles,
+            )
+            session.commit()
+            used_type = content_type or detect_content_type(path)
+            print(f"Ingested '{path}' as {len(docs)} chunk(s) ({used_type}) under source_url '{source_url}'.")
+    finally:
+        session.close()
+        engine.dispose()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="knowledge-grove")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    subparsers.add_parser(
+        "init-db", help="Run the bundled migrations against KNOWLEDGE_GROVE_DSN."
+    )
+
+    role_parser = subparsers.add_parser(
+        "create-agent-role", help="Provision a new agent's Postgres role."
+    )
+    role_parser.add_argument("role_name")
+    role_parser.add_argument(
+        "--password", help="If omitted, you'll be prompted (not echoed)."
+    )
+
+    ingest_parser = subparsers.add_parser(
+        "ingest", help="Add one or more files as documents, chunking each and computing embeddings."
+    )
+    ingest_parser.add_argument("files", nargs="+", help="Path(s) to the file(s) to ingest.")
+    ingest_parser.add_argument(
+        "--source-url", action="append", default=None,
+        help=(
+            "Source identifier, given once per file in the same order as `files`. "
+            "Defaults to each file's own filename (not a real URL -- just a stable "
+            "identifier so re-ingesting the same file later is recognized as an "
+            "update rather than a new, unrelated document)."
+        ),
+    )
+    ingest_parser.add_argument(
+        "--content-type", action="append", default=None, choices=list(ContentType),
+        help=(
+            "Chunker to use, given once per file in the same order as `files`. "
+            "Defaults to a guess from each file's extension (.py -> python, "
+            ".sql -> sql, everything else -> markdown)."
+        ),
+    )
+    ingest_parser.add_argument(
+        "--roles", default=None,
+        help=(
+            "JSON object granting other roles access to every document ingested "
+            "in this call, e.g. '{\"shared_reader\": [\"read\"]}'. Applies to the "
+            "whole call, not per file. Defaults to {\"shared_reader\": [\"read\"]} "
+            "if omitted; pass '{}' to keep everything private to the owner."
+        ),
+    )
+    ingest_parser.add_argument(
+        "-y", "--yes", action="store_true",
+        help="Don't prompt for confirmation when a source_url already has existing documents.",
+    )
+
+    args = parser.parse_args()
+
+    dsn = os.environ.get("KNOWLEDGE_GROVE_DSN")
+    if not dsn:
+        parser.error("KNOWLEDGE_GROVE_DSN must be set to a connection string")
+
+    if args.command == "init-db":
+        init_db(dsn)
+        print("Migrations applied.")
+    elif args.command == "create-agent-role":
+        password = args.password or getpass.getpass(f"Password for {args.role_name}: ")
+        agent_dsn = create_agent_role(dsn, args.role_name, password)
+        print(f"Role '{args.role_name}' created.")
+        print(f"Agent DSN: {agent_dsn}")
+    elif args.command == "ingest":
+        if args.source_url and len(args.source_url) != len(args.files):
+            parser.error("--source-url must be given once per file, or omitted entirely")
+        if args.content_type and len(args.content_type) != len(args.files):
+            parser.error("--content-type must be given once per file, or omitted entirely")
+        roles = None
+        if args.roles is not None:
+            try:
+                roles = json.loads(args.roles)
+            except json.JSONDecodeError as e:
+                parser.error(f"--roles must be valid JSON: {e}")
+        ingest_files(
+            dsn, args.files, source_urls=args.source_url,
+            content_types=args.content_type, roles=roles, assume_yes=args.yes,
+        )
+
+
+if __name__ == "__main__":
+    main()