vector-mcp 2.1.2__tar.gz → 3.3.1__tar.gz

{vector_mcp-2.1.2 → vector_mcp-3.3.1}/.pre-commit-config.yaml

@@ -1,5 +1,11 @@
+# Without this, `pre-commit install` wires ONLY the pre-commit hook, so `git push`
+# runs nothing and every hook staged pre-push is silently dead code.
+default_install_hook_types: [pre-commit, pre-push]
 default_language_version:
   python: python3
+# Phase 0 dev-velocity contract (arbora-completion-program): a hook with no
+# explicit `stages:` below is commit-only, never both.
+default_stages: [pre-commit]
 exclude: 'dotnet|node_modules'
 ci:
   autofix_prs: true
@@ -8,7 +14,7 @@ ci:
 
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v6.0.0
+  rev: 3e8a8703264a2f4a69428a0aa4dcb512790b2c8c # v6.0.0
   hooks:
   - id: check-added-large-files
     args: ["--maxkb=2000"]
@@ -25,54 +31,44 @@ repos:
   - id: end-of-file-fixer
   - id: no-commit-to-branch
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.15.8
+  rev: 38bfb07c0c64c304f47eb52090f8288150c77730 # v0.17.1
   hooks:
   - id: ruff
     types_or: [python, pyi, jupyter]
     args: ["--fix", "--ignore=E402"]
     exclude: ^(tests/|test/|scripts/|script/)
 - repo: https://github.com/jendrikseipp/vulture
-  rev: v2.16
+  rev: b0f67ba0044693aa9ec0d38fe460590facc98004 # v2.16
   hooks:
   - id: vulture
     pass_filenames: false
     args: [".", "--min-confidence", "95", --exclude, '.venv,venv,node_modules,.git,build,dist']     # or 100 if you want very high confidence only
     require_serial: true
 - repo: https://github.com/codespell-project/codespell
-  rev: v2.4.2
+  rev: 57b21406f092110c18776e39b0bda50d37c945c8 # v2.4.3
   hooks:
   - id: codespell
     args: ["-L", "ans,linar,nam,tread,ot,"]
 - repo: https://github.com/PyCQA/bandit
-  rev: 1.8.6
+  rev: 2d0b675b04c80ae42277e10500db06a0a37bae17 # 1.8.6
   hooks:
   - id: bandit
     args: ["--skip", "B101,B404,B603"]
     exclude: ^(tests/|test/|scripts/|script/|__tests__/)
 - repo: https://github.com/nbQA-dev/nbQA
-  rev: 1.9.1
+  rev: d31b7eae1767c43460afb3ba130e0a6602933abe # 1.9.1
   hooks:
   - id: nbqa-ruff
     exclude: ^(\.\/test/|\./tests/)
 - repo: local
   hooks:
-  - id: okf-no-legacy-concepts
-    name: OKF-CIS — no legacy CONCEPT ids
-    entry: python3 /home/apps/workspace/agent-packages/agent-utilities/scripts/check_no_legacy_markers.py .
+  - id: dependency-readiness
+    name: Dependency readiness — every declared intra-fleet constraint is installable
+    entry: bash -c 'P=""; d="$PWD"; while [ "$d" != "/" ]; do [ -d "$d/agent-packages/agents/repository-manager" ] && { P="$d/agent-packages/agents/repository-manager"; break; }; d=$(dirname "$d"); done; [ -n "$P" ] || P=repository-manager; uv run --no-project --python 3.12 --prerelease=allow --with "$P" python -m repository_manager.dependency_readiness .'
     language: system
     pass_filenames: false
     always_run: true
-  - id: check-mermaid
-    name: Check Mermaid syntax
-    entry: python3 /home/apps/workspace/agent-packages/agent-utilities/scripts/mermaid_linter.py
-    language: system
-    files: \.md$
-    pass_filenames: true
-  - id: check-stubs
-    name: Check for Active Stubs and TODOs
-    entry: python3 /home/apps/workspace/agent-packages/agent-utilities/scripts/check_stubs.py
-    language: system
-    types: [python]
+    stages: [manual, pre-push]
   - id: mermaid-validate
     name: mermaid-validate
     entry: mermaid-validate
@@ -83,41 +79,20 @@ repos:
   - id: check-agent-standards
     name: check agent standards
     entry: |-
-      bash -c 'for f in $(find . -type f -name "agent_server.py" -not -path "*/\.venv/*" -not -path "*/__pycache__/*"); do grep -q "warnings.filterwarnings" "$f" && grep -q "file=sys.stderr" "$f" || { echo "Missing warnings.filterwarnings or file=sys.stderr in $f"; exit 1; }; done'
+      bash -c 'for f in $(find . -type f -name "mcp_server.py" -not -path "*/\.venv/*" -not -path "*/__pycache__/*"); do grep -q "warnings.filterwarnings\|import warnings" "$f" || { echo "Missing warnings.filterwarnings in $f"; exit 1; }; done'
     language: system
     pass_filenames: false
     always_run: true
-  - id: mcp-readme-table
-    name: sync MCP tools table in README
-    entry: |-
-      bash -c 'if [ -f uv.lock ]; then uv run python -m agent_utilities.mcp.readme_tools; else python -m agent_utilities.mcp.readme_tools; fi'
-    language: system
-    files: ^(README\.md|.*/mcp_server\.py|.*/mcp/.*\.py)$
-    pass_filenames: false
-  - id: readme-env-vars
-    name: sync env-vars table in README
-    entry: |-
-      bash -c 'if [ -f uv.lock ]; then uv run python -m agent_utilities.mcp.readme_env_vars; else python -m agent_utilities.mcp.readme_env_vars; fi'
-    language: system
-    files: ^(README\.md|\.env\.example)$
-    pass_filenames: false
-  - id: readme-mcp-examples
-    name: sync mcp_config examples in README + env blocks
-    entry: |-
-      bash -c 'if [ -f uv.lock ]; then uv run python -m agent_utilities.mcp.readme_mcp_examples; else python -m agent_utilities.mcp.readme_mcp_examples; fi'
-    language: system
-    files: ^(README\.md|\.env\.example|mcp_config.*\.json|.*/mcp_config.*\.json|.*/mcp_server\.py)$
-    pass_filenames: false
   - id: env-var-drift
     name: check env-var/config drift
-    entry: bash -c 'if [ -f uv.lock ]; then uv run python -m agent_utilities.mcp.check_env_var_drift --check; else python -m agent_utilities.mcp.check_env_var_drift --check; fi'
+    entry: bash -c 'if [ -f uv.lock ]; then uv run python -m agent_connector_sdk.mcp.env_drift --check; else python -m agent_connector_sdk.mcp.env_drift --check; fi'
     language: system
     pass_filenames: false
     files: ^(README\.md|\.env\.example|mcp_config.*\.json|.*/mcp_config.*\.json|docker/.*compose.*\.ya?ml|.*/auth\.py|.*/mcp_server\.py)$
   - id: check-cli-help
     name: check cli help
     entry: |-
-      bash -c 'for f in $(find . -type f \( -name "mcp_server.py" -o -name "agent_server.py" \) -not -path "*/\.venv/*" -not -path "*/__pycache__/*"); do mod=$(echo "$f" | sed -e "s/^\.\///" -e "s/\.py$//" -e "s/\//./g"); uv run python -m "$mod" --help >/dev/null || exit 1; done'
+      bash -c 'for f in $(find . -type f \( -name "mcp_server.py" -o -name "mcp_server.py" \) -not -path "*/\.venv/*" -not -path "*/__pycache__/*"); do mod=$(echo "$f" | sed -e "s/^\.\///" -e "s/\.py$//" -e "s/\//./g"); uv run python -m "$mod" --help >/dev/null || exit 1; done'
     language: system
     pass_filenames: false
     always_run: true
@@ -129,7 +104,7 @@ repos:
     pass_filenames: false
     always_run: true
 - repo: https://github.com/AleksaC/hadolint-py
-  rev: v2.14.0
+  rev: 6e7504451511eaeb62a3e7f14d63b0296cbf86eb # v2.15.1
   hooks:
   - id: hadolint
     args:
@@ -139,7 +114,7 @@ repos:
     - --ignore=DL4006
     - --ignore=SC2102
 - repo: https://github.com/IamTheFij/docker-pre-commit
-  rev: v3.0.1
+  rev: f626253b23de45412865c07fd076ff95d4cd77a7 # v3.0.1
   hooks:
   - id: docker-compose-check
 - repo: local

vector_mcp-3.3.1/AGENTS.md

@@ -0,0 +1,231 @@
+# AGENTS.md
+
+<!-- agent-contract:start -->
+## Agent contract
+
+Tool-neutral rules for any AI agent or human working in this repository. This block is maintained by the fleet standard; edit outside the markers.
+
+- **Owner boundary:** this repository owns one external system's calls, mappings and MCP tools (spec prefix `CONN-VECTOR-MCP-`); it depends on the connector SDK only. Feature routing across repositories: [ecosystem boundaries](https://github.com/Knuckles-Team/pipelines/blob/main/reference/ecosystem-boundaries.md).
+- **Setup:** run `scripts/bootstrap.sh`. It is idempotent and non-interactive: it pins uv and Python, syncs the locked environment, installs the git hooks and prints the gate command.
+- **Gates:** `uvx pre-commit run --all-files` must pass before you push. Do not bypass hooks to get green.
+- **Commits:** one logical change per commit with a `Spec: <ID>` trailer (or `Spec: none (<reason>)`), plus a `Co-Authored-By:` trailer naming the assisting agent. Stage explicit paths only; never `git add -A` or `git add .`. Use your own configured Git identity, never a tool or bot name.
+- **Org rules:** [organization AGENTS.md](https://github.com/Knuckles-Team/.github/blob/main/AGENTS.md).
+<!-- agent-contract:end -->
+
+## Scope
+
+This repository provides the action-routed `vector-mcp` server, optional vector provider
+adapters, an agent entry point, packaged skills/prompts, a vector ontology, and a read-only
+collection-inventory connector preset.
+
+- Language/Version: Python 3.11+
+- Core Libraries: `agent-connector-sdk`, `fastmcp`, `epistemic-graph` (client)
+- Key principles: Functional patterns, Pydantic for data validation, asynchronous tool execution.
+
+## Current architecture
+
+```text
+MCP client
+  -> vector_collection_management / vector_search
+  -> validation, privacy, and backend policy
+  -> verified GraphSession boundary
+  -> configured provider
+```
+
+Epistemic-graph is the native default. Optional providers are isolated behind extras and imported
+only when selected.
+
+## Non-negotiable design rules
+
+- Do not add legacy paths, fallback implementations, deprecated aliases, compatibility shims, or
+  backward-compatibility branches. Migrate the current contract directly.
+- Do not accept credentials or local database paths as MCP tool arguments.
+- Do not persist endpoints, credentials, personal identity, raw content, hostnames, or local
+  filesystem paths in source, skills, docs, traces, reports, fixtures, or generated evidence.
+- Resolve runtime values through AgentConfig, environment variables, and supported secret
+  references.
+- Resolve TLS through the shared transport profile. Do not add certificate-verification bypasses.
+- Keep document ingestion confined to the configured root and relative caller-selected paths.
+- Keep optional dependencies lazy; importing `vector_mcp` must not start services or require
+  every provider SDK.
+- Never fabricate connector signatures, live test evidence, trace evidence, or safe dependency
+  versions.
+
+## Source layout
+
+- `vector_mcp/mcp_server.py`: condensed MCP registration and request boundary
+- `vector_mcp/vector_api.py`: checked session, privacy, secret, TLS, and provider boundary
+- `vector_mcp/vectordb/`: optional provider adapters
+- `vector_mcp/backend_policy.py`: canonical backend and exposure policy
+- `vector_mcp/document_inputs.py`: bounded root-confined ingestion inputs
+- `vector_mcp/doctor.py`: privacy-safe readiness output
+- `vector_mcp/skills/`, `prompts/`, `ontology/`, `connectors/`: packaged extensions
+- `tests/`: unit and explicitly configured integration tests
+- `docs/`: operator documentation
+
+### Supported backends
+
+- **Epistemic-Graph** (**DEFAULT**): the native local AI-native engine — durable
+  (redb-authoritative) with a native ANN/HNSW index, so semantic search is the engine's
+  O(log N) vector search. Zero external infra (autostarts). Selected when `db_type` is
+  unspecified (override with `DATABASE_TYPE`, alias `VECTOR_DB_TYPE`).
+- **PostgreSQL/PGVector**, **Qdrant**, **MongoDB**: secure opt-in providers, TLS-checked and
+  secret-reference-only — the current, certified contract (`VectorDBFactory.PREDEFINED_VECTOR_DB`
+  and `backend_policy.ensure_backend_available` agree on exactly these four names, and both the
+  factory and the MCP tool boundary reject any other `db_type`, including legacy spellings like
+  `eg`/`epistemic-graph`).
+- **ChromaDB / Couchbase — removed from the supported contract.** `vector_mcp/vectordb/chromadb.py`
+  and `couchbase.py` remain in the tree (real, previously-shipped adapters) but are no longer wired
+  into `VectorDBFactory`, `vectordb.__init__`'s exports, or the packaged extras —
+  `db_type="chroma"|"couchbase"` raises `vector_database_type_unsupported` (see
+  `tests/test_protocol_compliance.py`, `tests/test_database_transport_security.py`). They can still
+  be imported directly (`from vector_mcp.vectordb.chromadb import ChromaVectorDB`) by a caller who
+  installs `chromadb`/`couchbase` + `llama-index` themselves, but that path is unsupported/untested
+  by the current contract.
+
+### Implementation notes
+
+- **Epistemic-Graph**: stores each chunk as an engine node (text in the indexed
+  `description` property, plus metadata) with its embedding in the engine's native ANN
+  index via `SyncEpistemicGraphClient` (transactional `.txn.add_node` + `.txn.add_embedding`,
+  session-authority-cached connections). Semantic search is `.graph.semantic_search` (native
+  ANN); lexical/keyword search is the engine's one-round-trip `.graph.discover` (keyword overlap
+  + semantic, scalable — a client-side term scan is only a fallback for an engine too old for
+  `discover`). A collection maps to an engine graph (`graph_name`); embeddings come from the
+  shared `create_embedding_model`.
+- **PostgreSQL / Qdrant / MongoDB**: rewritten on raw `psycopg`/`qdrant_client`/`pymongo` (no
+  `llama-index` dependency) behind the shared TLS-pinned transport layer.
+
+Removed root-level debug scripts and obsolete test compose artifacts must remain removed.
+Maintained container definitions live under `docker/`.
+
+## Development rules
+
+- Use `agent_connector_sdk` primitives for MCP construction, secrets, identity, transport
+  security, and observability.
+- Keep public tool schemas bounded and explicit.
+- Use Pydantic fields/models where they define a public validation boundary.
+- Log stable status and exception types, not values or response bodies.
+- Require runtime credentials for integration tests; never provide checked-in password defaults.
+- Preserve unrelated user work and do not commit caches, databases, traces, logs, build outputs,
+  or environment files.
+- Keep `pyproject.toml`, module versions, and `uv.lock` synchronized. Do not regenerate the
+  lock as a side effect of unrelated work.
+
+## Cheap validation
+
+These checks do not start providers:
+
+```bash
+python scripts/security_sanitizer.py
+python scripts/security_contract.py --contract .security/security-contract.json validate
+python -m compileall -q vector_mcp
+```
+
+Also parse JSON/TOML/YAML, run `git diff --check`, and run the configured formatter/linter.
+Provider tests, services, lock regeneration, and native compilation are separate serialized gates
+and must not be run concurrently on a constrained workstation.
+
+## Connector evidence
+
+The source preset follows the installed action-routed tool schema. Exact tool-schema fingerprints,
+connector manifests, and certification files are generated release evidence. Generate them only
+after observing the installed MCP schema and resolving an authorized runtime signing key. If
+source ontology or tool schemas change, old signatures are invalid and must not be copied forward.
+
+## ⛔ Keep the Repository Root Pristine — No Scratch / Temp / Debug Files
+
+**The repository ROOT must contain only canonical project files** (packaging,
+config, docs, lockfiles). The only hidden directories allowed at root are
+`.git/`, `.github/`, and `.specify/` (plus a local, git-ignored `.venv/`).
+
+**NEVER write any of the following — anywhere in the repo, and ESPECIALLY at the root:**
+- One-off / debug / migration scripts: `fix_*.py`, `migrate_*.py`, `refactor_*.py`,
+  `replace_*.py`, `update_*.py`, `debug_*.py`, or `test_*.py` **at the root**
+  (real tests live in `tests/` only).
+- Databases / data dumps: `*.db`, `*.db-wal`, `*.sqlite*`, `*.corrupted`.
+- Logs / command output: `*.log`, scratch `*.txt`, `*.orig`, `*.rej`, `*.bak`.
+- Build artifacts: `*.tsbuildinfo`, compiled binaries, coverage files.
+- AI agent scratch directories: `.agent/`, `.agents/`, `.agent_data/`, `.tmp/`,
+  `.hypothesis/`, or any per-tool cache committed to git.
+- Any file that is NOT production source, a test in `tests/`, documentation, or
+  a recognized config/lockfile.
+
+**Why:** these files expose private filesystem paths, credentials, and internal infrastructure
+details when pushed to GitHub publicly; scratch at the root also bloats the tree and erodes a
+pristine codebase.
+
+**Where to put scratch work instead:**
+- Use `~/workspace/scratch/` for temporary scripts and experiments
+- Use `~/workspace/reports/` for command output and reports
+- Keep test scripts in the `tests/` directory following proper pytest conventions
+
+Before finishing a task, run `git status` and confirm no stray root files were added.
+
+<!-- BEGIN concept-coordination (generated) -->
+## Concept-ID Coordination (multi-session)
+
+Working in parallel with other sessions/worktrees? **Reserve a concept id before you write its `CONCEPT:` marker** so two sessions never collide:
+
+```bash
+agent-utilities --json concept reserve --ns EG-KG.compute.backend   # or a package prefix, e.g. KEY
+```
+
+Full protocol (ledger, merge=union, reconcile, MCP/REST): <https://knuckles-team.github.io/agent-utilities/concept_coordination/>
+<!-- END concept-coordination (generated) -->
+
+## Version & lockfile drift edict (keep the version mirrors AND the lock in sync)
+
+The two most common release-breakers in this fleet are **version drift** (the version in
+`pyproject.toml`/`.bumpversion.cfg` advancing while `README.md`, `docker/Dockerfile`, and the
+module `__version__`s lag) and a **stale `uv.lock`** (shipping known-vulnerable transitive deps).
+A version mismatch makes the next `bump-my-version` throw `VersionNotFoundException`; a stale lock
+is what Dependabot flags. Rules:
+
+1. **Never hand-edit a version string.** Change the version ONLY via
+   `bump-my-version bump {patch|minor|major}` (a.k.a. `bump2version`), which rewrites every file
+   registered in `.bumpversion.cfg` in one atomic, tagged commit. If the operator edited the version in
+   `pyproject.toml` by hand, the operator created drift — revert and use the bumper.
+2. **Every version-bearing file must be registered in `.bumpversion.cfg`** — at minimum
+   `pyproject.toml` AND `README.md`, plus `docker/Dockerfile` and any module `__version__`. Never
+   add a file that embeds the version without a `[bumpversion:file:...]` entry for it.
+3. **Re-lock on every dependency change.** After editing `pyproject.toml` deps/extras, run
+   `uv lock` and commit `uv.lock` in the SAME change. The `uv-lock` pre-commit hook runs with
+   `--locked` and fails on drift — never bypass it. The committed `uv.lock` is the
+   Dependabot/security surface.
+4. **Patch CVEs with a version floor at the source, then re-lock.** `uv` resolves one version
+   graph-wide, so a lower-bound in the extra that pulls a dependency raises it for the whole lock.
+
+## Upstream currency edict — target the newest release; a pin is a hypothesis, not a fact (READ BEFORE capping, deferring, or opt-in-gating an upgrade)
+
+This governs how this repository treat **other people's** releases, deprecations, and version caps in
+this repo (fleet-wide edict, propagated from `agent-utilities/AGENTS.md`).
+
+1. **Latest by default.** Target the newest upstream release -- including a pre-release
+   where the ecosystem has already moved onto it. Sitting on an old major because the
+   upgrade is work is not a reason to defer it.
+2. **A conservative upstream pin is a hypothesis, not a fact -- test it, don't inherit
+   it.** Upstream maintainers cap defensively (an unreleased major, an untested surface)
+   as often as they cap for a known break. Worked example (from `agent-utilities`):
+   `pydantic-ai-slim` 2.18.0 declared `fastmcp-slim[client]>=3.3.0` with no upper bound;
+   2.19.0 added `<4` purely as a defensive guard while fastmcp 4 was still pre-release --
+   not because of an observed incompatibility. Blocking an upgrade on that kind of cap
+   without testing it is the wrong default.
+3. **Forward-fix only.** When an upgrade breaks something, fix the break to proceed --
+   do not pin backwards, vendor a fork, or route around it. If a break is genuinely
+   unfixable inside this repo, say exactly what and why, and carry a plan to unblock it
+   -- never an indefinite pin.
+4. **Deprecations are fixed on sight, in code AND in tests.** A `DeprecationWarning` from
+   an upstream library is a defect to fix now, not noise to filter. **Never** silence one
+   with a warning filter, `# noqa`, or a pytest `filterwarnings` entry to go
+   green.
+5. **Adopt upstream features rather than reimplementing them.** If upstream ships a
+   capability this repo hand-rolled, migrate to theirs and remove the local one.
+6. **Nothing built on an upgrade ships opt-in.** A new capability an upgrade unlocks is
+   default-on unless it genuinely costs compute, in which case it is policy-selected,
+   never flag-gated. An opt-in extra or a dependency-conflict fork is an interim state
+   that must carry a written plan to become the default, never a resting place.
+
+## Specs: extend first
+
+Find the spec row that owns the behavior before any code change. Search with `git grep -n "<term>" -- specs`. Cite the row ID in the commit `Spec:` trailer. Extend the owning spec before any new spec text. Add a child row, a new rollup, or a dated `plan.md` "Amendments" entry. Create a new spec only for a capability that no spec owns. Audits, reviews, and carry-overs land in the owning spec. They never get a spec directory. Reuse an existing function, module, or store before adding one. The rules are the ecosystem [spec standard](https://github.com/Knuckles-Team/pipelines/blob/main/reference/spec-standard.md).

{vector_mcp-2.1.2 → vector_mcp-3.3.1}/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2012-2023 Audel Rouhi
+Copyright (c) 2012-2023 Project Maintainers
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the