patchvec 0.5.6__py3-none-any.whl

patchvec-0.5.6.dist-info/METADATA

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: patchvec
+Version: 0.5.6
+Summary: Patchvec — A lightweight, pluggable vector search microservice.
+Author: Rodrigo Rodrigues da Silva
+Author-email: rodrigopitanga@posteo.net
+License: GPL-3.0-or-later
+Project-URL: Homepage, https://gitlab.com/flowlexi/patchvec
+Project-URL: Source, https://gitlab.com/flowlexi/patchvec
+Project-URL: Tracker, https://gitlab.com/flowlexi/patchvec/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Database
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn[standard]>=0.30.6
+Requires-Dist: txtai>=6.3.0
+Requires-Dist: pydantic>=2.8.2
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: pypdf>=5.0.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: qdrant-client>=1.9.2
+Requires-Dist: sentence-transformers>=2.7.0
+Requires-Dist: openai>=1.0.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# PatchVec — A lightweight, pluggable vector search microservice.
+
+Upload → chunk → index (with metadata) → search via REST and CLI.
+
+## Highlights
+- Multi-tenant collections: `/collections/{tenant}/{name}`
+- Upload and search **TXT**, **CSV**, and **PDF**
+- Chunking per format:
+  - PDF → 1 chunk/page
+  - TXT → configurable chunk size + overlap
+  - CSV → 1 chunk/row
+- Metadata filters on POST search (`{"filters": {"docid": "DOC-1"}}`)
+- Health, metrics, and Prometheus endpoints
+- Configurable auth modes: `none` or `static` (Bearer)
+- Default backends are local (vendor-neutral "default"); embedders & stores are pluggable
+
+## Requirements
+- Python 3.10+
+
+## Install
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install patchvec
+```
+
+> CPU-only by default. If you have a CUDA setup and want GPU-accelerated deps, install the GPU-enabled packages in your environment before running PatchVec.
+
+## Quickstart
+```bash
+# Start the server (installed entry point)
+pavesrv
+
+# Or run with uvicorn manually if you prefer:
+uvicorn pave.main:app --host 0.0.0.0 --port 8080
+```
+
+## Minimal config (optional)
+By default PatchVec runs with sensible local defaults. To customize, create `config.yml` and set:
+```yaml
+vector_store:
+  type: default
+embedder:
+  type: default
+auth:
+  mode: none    # or 'static' with per-tenant Bearer keys
+```
+Then export:
+```bash
+export PATCHVEC_CONFIG=./config.yml
+```
+
+## REST example
+```bash
+# Create a collection
+curl -X POST http://localhost:8080/collections/acme/docs
+
+# Upload a TXT document
+curl -X POST http://localhost:8080/collections/acme/docs/documents   -F "file=@sample.txt" -F "docid=DOC1"
+
+# Search (GET, no filters)
+curl -G --data-urlencode "q=hello" http://localhost:8080/collections/acme/docs/search
+
+# Search (POST, with filters)
+curl -X POST http://localhost:8080/collections/acme/docs/search   -H "Content-Type: application/json"   -d '{"q":"hello","k":5,"filters":{"docid":"DOC1"}}'
+```
+
+## License
+GPL-3.0-or-later — (C) 2025 Rodrigo Rodrigues da Silva

patchvec-0.5.6.dist-info/RECORD

@@ -0,0 +1,28 @@
+patchvec-0.5.6.dist-info/licenses/LICENSE,sha256=pZN4UctsMWb-i8NGK_cawTQZ_uIYTR98GPAPzhRJXOM,299
+pave/__init__.py,sha256=49d6bp1SBYCw7mk4wu_qO9mASeZVqYqsbuzKmxAtT7s,223
+pave/auth.py,sha256=PVKA243OKvs0jaob-DJk6EMRzlBR9Qc2lNedlFUfjG8,3674
+pave/cli.py,sha256=pLqQcA9awbvxGLxCzAcOcj1sdkPm2g3eNA7TXdngnpk,3649
+pave/config.py,sha256=j6veVNb-tUzo_TnbzYpTR1Q2TDxmqHbMs152J4DFnFU,7876
+pave/main.py,sha256=siufImb2qdxZvMJ4PHsbIKFDDskWqOzasFnjMph_g28,9736
+pave/metrics.py,sha256=qqhvLCCzY2sgmjgsnNBnRxoZ5xTe9RW5DvoGMQiQAZg,1588
+pave/preprocess.py,sha256=-llfKyWJ6aOPQ-y7XFmoJwF_9r34MnyqVbCghd8J-Vc,5392
+pave/service.py,sha256=x1wu1yQd99Lmt4JvdvvKxQNhZgzkQ4u80p8P6oAxP_Y,3602
+pave/ui.py,sha256=GQ0iRcCAP9UMdT_M0m7JDQhawrqaop6I-opivGMR0hE,6345
+pave/assets/patchvec_icon_192.png,sha256=kUkXir9MtwxWTd_9hPTdycDwdRCimjprJhmaIP6R-XM,9733
+pave/assets/ui.html,sha256=spFtzCDT84tmJfCA1WdpVY9xKKQ4oXJxjuOiV4ghWJo,4943
+pave/embedders/__init__.py,sha256=Y6PqISvtEzZ5xLK2nL0jsQ256X8ffVn39Md05OS0SDk,6
+pave/embedders/base.py,sha256=bm3mTOEt_sN-V96QmIKSW882LhIxsAyR0NMCaVvY7CM,364
+pave/embedders/factory.py,sha256=-cxlFpDxWqbODEZ4vcZArFAdvoAdc4WATEePk7whCEo,803
+pave/embedders/openai_emb.py,sha256=EDEULYNbB4uuH7axsLCSLqmuNmQ43jEUWYS_mcnBlR8,1135
+pave/embedders/sbert_emb.py,sha256=cnposbN1f2SYR31aR06PUPI_ZGaQ0qCA9dFtxaCLf_M,968
+pave/embedders/txtai_emb.py,sha256=00VTIil1SI5hT0-4GfPYYnT-EtKgBjoaZ57dSCeXjUU,2233
+pave/stores/__init__.py,sha256=Y6PqISvtEzZ5xLK2nL0jsQ256X8ffVn39Md05OS0SDk,6
+pave/stores/base.py,sha256=zxDEN6cpWLIPmYeo1GjXx2hoBB-xZuZR7Bd-FI8J9kQ,1111
+pave/stores/factory.py,sha256=LqIwkwXz9rOQGTPfKu9VonxqoXUWhWSk0OEIiCu3FRs,634
+pave/stores/qdrant_store.py,sha256=18tTn5V4NDDKAtjjgsPP7GKiLhZmxhrs2APUKs8-9os,1159
+pave/stores/txtai_store.py,sha256=2HKgvGNHYsuQtbOjHkgYoF-Zde-LuLMV6lqVMFLSsJo,16227
+patchvec-0.5.6.dist-info/METADATA,sha256=lgLS6YG89YYa-Ei-G364BdQv3jMPtV96L3kTDzMuRkg,3643
+patchvec-0.5.6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+patchvec-0.5.6.dist-info/entry_points.txt,sha256=L6cnN4Byk5eDON2d4ipquuLowUjo7-5wpxLb-kThytQ,75
+patchvec-0.5.6.dist-info/top_level.txt,sha256=AbaAN6M4jryKL79DrYPnt49TpE2sjp97qYmm31RD_-U,5
+patchvec-0.5.6.dist-info/RECORD,,

patchvec-0.5.6.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

patchvec-0.5.6.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+pavecli = pave.cli:main_cli
+pavesrv = pave.main:main_srv

patchvec-0.5.6.dist-info/licenses/LICENSE

@@ -0,0 +1,9 @@
+GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright (C) 2025 Rodrigo Rodrigues da Silva <rodrigopitanga@posteo.net>
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+Full text: https://www.gnu.org/licenses/gpl-3.0.txt

patchvec-0.5.6.dist-info/top_level.txt

@@ -0,0 +1 @@
+pave

pave/__init__.py

@@ -0,0 +1,6 @@
+# (C) 2025 Rodrigo Rodrigues da Silva <rodrigopitanga@posteo.net>
+# SPDX-License-Identifier: GPL-3.0-or-later
+__all__ = [
+    "config", "auth", "preprocess", "metrics", "service", "main", "cli",
+    "embedders", "stores"
+]

pave/assets/ui.html

@@ -0,0 +1,125 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width,initial-scale=1" />
+<!-- favicon robusto -->
+<link rel="icon" type="image/png" sizes="32x32" href="/assets/patchvec_icon_192.png" />
+<link rel="icon" type="image/png" sizes="192x192" href="/assets/patchvec_icon_192.png" />
+<link rel="icon" href="/favicon.ico" />
+<title>__INST_NAME__ • Search</title>
+<style>
+  /* paleta */
+  :root{ --bg:#f6e6d9; --panel:#fffaf6; --text:#2b1e11; --muted:#6b5b53; --accent:#c9463d; --border:#ead7c7; --link:#0f2e4d; --link-accent:#14b8a6; }
+  @media (prefers-color-scheme: dark){
+    :root{ --bg:#1a1410; --panel:#221a14; --text:#f1e9e4; --muted:#b7a9a1; --accent:#ef6b62; --border:#3a2c22; --link:#9dd9d3; --link-accent:#34d399; }
+  }
+
+  *{ box-sizing:border-box }
+  html,body{ height:100% }
+  body{
+    min-height:100vh; display:flex; flex-direction:column; overflow:hidden;
+    margin:0; font:16px/1.45 system-ui,Segoe UI,Roboto,Inter,Arial; background:var(--bg); color:var(--text);
+  }
+
+  .bar{
+    flex:0 0 auto; display:flex; gap:10px; align-items:center;
+    padding:12px; border-bottom:1px solid var(--border); background:var(--panel);
+  }
+  .left{ display:flex; gap:8px; align-items:center }
+  .right{ margin-left:auto; color:var(--muted); white-space:nowrap; overflow:hidden; text-overflow:ellipsis }
+
+  .tab{
+    padding:8px 12px; border-radius:10px; border:1px solid var(--border);
+    cursor:pointer; background:transparent; color:var(--text);
+  }
+  .tab.active{ background:var(--link-accent); color:#041318; border-color:var(--link-accent) }
+
+  .frames{ flex:1 1 auto; min-height:0; background:var(--bg) }
+  .frame{ display:none; width:100%; height:100%; border:0; background:var(--bg) }
+  .frame.active{ display:block }
+
+  .footer{
+    flex:0 0 auto; position:sticky; bottom:0;
+    display:flex; gap:12px; align-items:center; justify-content:center;
+    padding:10px; color:var(--muted); border-top:1px solid var(--border); background:var(--panel);
+  }
+  .footer a{ color:var(--link); text-decoration:none }
+  .footer a:hover{ color:var(--link-accent) }
+</style>
+</head>
+<body>
+  <div class="bar">
+    <div class="left">
+      <button class="tab active" data-target="search" data-title="__INST_NAME__ • Search">Search</button>
+      <button class="tab" data-target="ingest" data-title="__INST_NAME__ • Ingest">Ingest</button>
+    </div>
+    <div class="right"><strong>__INST_NAME__</strong> — <small>__INST_DESC__</small></div>
+  </div>
+
+  <div class="frames">
+    <iframe id="search" class="frame active" src="/ui/search" title="Search"></iframe>
+    <iframe id="ingest" class="frame" src="/ui/ingest" title="Ingest"></iframe>
+  </div>
+
+  <div class="footer">
+    © 2025 <a href="https://flowlexi.com" target="_blank" rel="noopener">Flowlexi</a> •
+    <a href="__REPO_URL__" target="_blank" rel="noopener">🍰 patchvec __VERSION__</a> •
+    <a href="__LICENSE_URL__" target="_blank" rel="noopener">__LICENSE_NAME__</a>
+  </div>
+<script>
+  function activeFrame(){ return document.querySelector('.frame.active'); }
+
+  function scrubSwagger(frame){
+    const win = frame?.contentWindow;
+    const doc = win?.document;
+    if(!doc) return;
+    if(!doc.querySelector('.swagger-ui')){
+      setTimeout(()=>scrubSwagger(frame), 80);
+      return;
+    }
+
+    // CSS: remove topo/infos
+    const STYLE_ID = 'pv-clean';
+    if(!doc.getElementById(STYLE_ID)){
+      const s = doc.createElement('style');
+      s.id = STYLE_ID;
+      s.textContent = `
+        #operations-tag-default,
+        .swagger-ui .topbar,
+        .swagger-ui .download-url-wrapper,
+        .swagger-ui .information-container,
+        .swagger-ui .info,
+        .swagger-ui .servers { display:none !important; }
+        .swagger-ui .wrapper { margin:0 !important; padding:0 0 8px !important; }
+        html, body { background:transparent !important; }
+        /* auth icon */
+        .swagger-ui .auth-wrapper .authorize:hover { border-color: rgba(20,184,166,.8); }
+        .swagger-ui .btn.authorize { background: white }
+        .swagger-ui .scheme-container { width:100%; height:; margin: 8px 0 0 0; padding: 0 0; background:transparent; border-color: transparent; box-shadow:0 0 0 0 rgba(0,0,0,0)}
+      `;
+      doc.head.appendChild(s);
+    }
+  }
+
+  const tabs = document.querySelectorAll('.tab');
+  const frames = document.querySelectorAll('.frame');
+
+  tabs.forEach(function(tab){
+    tab.addEventListener('click', function(){
+      tabs.forEach(t=>t.classList.remove('active'));
+      frames.forEach(f=>f.classList.remove('active'));
+      tab.classList.add('active');
+      const fr = document.getElementById(tab.dataset.target);
+      fr.classList.add('active');
+      document.title = tab.dataset.title || document.title;
+      scrubSwagger(fr);
+    });
+  });
+
+  frames.forEach(function(fr){
+      fr.addEventListener('load', function(){ scrubSwagger(fr); });
+  });
+</script>
+</body>
+</html>

pave/auth.py

@@ -0,0 +1,108 @@
+# (C) 2025 Rodrigo Rodrigues da Silva <rodrigopitanga@posteo.net>
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# pave/auth.py
+
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Optional, Dict, Tuple
+from fastapi import HTTPException, Depends, Security
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from . import config as cfg
+
+bearer = HTTPBearer(auto_error=False)
+
+@dataclass
+class AuthContext:
+    tenant: Optional[str]
+    is_admin: bool
+
+def _raise_401():
+    raise HTTPException(
+        status_code=401,
+        detail="missing or invalid authorization header",
+        headers={"WWW-Authenticate": 'Bearer realm="patchvec", error="invalid_token"'},
+    )
+
+def _raise_403():
+    raise HTTPException(
+        status_code=403,
+        detail="forbidden",
+        headers={"WWW-Authenticate": 'Bearer realm="patchvec", error="insufficient_scope"'},
+    )
+
+def auth_ctx(credentials: HTTPAuthorizationCredentials | None = Security(bearer)) -> AuthContext:
+    # read from CFG.get so tests and env overrides work
+    mode = str(cfg.CFG.get("auth.mode", "none")).strip().lower()
+
+    if mode == "none":
+        # open mode (dev): treat as admin
+        return AuthContext(tenant=str(cfg.CFG.get("auth.default_access_tenant", None)), is_admin=True)
+
+    if mode == "static":
+        token = credentials.credentials.strip() if credentials and credentials.scheme == "Bearer" else None
+        if not token:
+            _raise_401()
+
+        # global key
+        global_key = cfg.CFG.get("auth.global_key")
+        if global_key and token == str(global_key):
+            return AuthContext(tenant=None, is_admin=True)
+
+        # per-tenant keys
+        api_keys: Dict[str, str] = cfg.CFG.get("auth.api_keys", {}) or {}
+        for t, expected in api_keys.items():
+            if token == str(expected):
+                return AuthContext(tenant=t, is_admin=False)
+
+        _raise_403()
+
+    raise HTTPException(status_code=500, detail=f"unknown auth mode: {mode}")
+
+def authorize_tenant(tenant: str, ctx: AuthContext = Depends(auth_ctx)) -> AuthContext:
+    if ctx.is_admin or ctx.tenant == tenant:
+        return ctx
+    _raise_403()
+
+
+# --- Startup security policy -------------------------------------------------
+
+def _is_dev(cfg) -> bool:
+    # check dev flag (CFG or PATCHVEC_DEV)
+    return bool(cfg.get("dev", False)) or str(cfg.get("PATCHVEC_DEV", "0")) == "1"
+
+def enforce_policy(cfg) -> None:
+    """
+    Fail fast if auth is not configured in prod.
+    Allow auth=none only in dev mode, force loopback bind.
+    """
+    mode = str(cfg.get("auth.mode", "none")).strip().lower()
+    dev = _is_dev(cfg)
+
+    if mode == "none":
+        if not dev:
+            raise RuntimeError(
+                "auth.mode=none not allowed in production. "
+                "Set auth.mode=static with a key or run with PATCHVEC_DEV=1 for dev."
+            )
+        host = str(cfg.get("server.host", "127.0.0.1")).strip()
+        if host not in ("127.0.0.1", "localhost"):
+            # enforce loopback in dev
+            try:
+                cfg._data["server.host"] = "127.0.0.1"
+            except Exception:
+                pass
+
+    if mode == "static":
+        has_global = bool(cfg.get("auth.global_key"))
+        has_map = bool(cfg.get("auth.api_keys"))
+        if not (has_global or has_map):
+            raise RuntimeError(
+                "auth.mode=static requires global_key or api_keys"
+            )
+
+def resolve_bind(cfg) -> Tuple[str, int]:
+    # return host/port after policy enforcement
+    host = str(cfg.get("server.host", "127.0.0.1"))
+    port = int(cfg.get("server.port", 8086))
+    return host, port

pave/cli.py

@@ -0,0 +1,97 @@
+# (C) 2025 Rodrigo Rodrigues da Silva <rodrigopitanga@posteo.net>
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import annotations
+import argparse, json, uuid, pathlib
+from pave.stores.factory import get_store
+from pave.service import (
+    create_collection as svc_create_collection,
+    delete_collection as svc_delete_collection,
+    ingest_document as svc_ingest_document,
+    do_search as svc_do_search,
+)
+from pave.config import get_cfg, reload_cfg
+
+store = get_store(get_cfg())
+
+def _read(path: str) -> bytes:
+    return pathlib.Path(path).read_bytes()
+
+def cmd_create(args):
+    out = svc_create_collection(store, args.tenant, args.collection)
+    print(json.dumps(out, ensure_ascii=False))
+
+def cmd_upload(args):
+    baseid = args.docid or str(uuid.uuid4())
+    meta = json.loads(args.metadata) if args.metadata else {}
+    content = _read(args.file)
+
+    # CSV controls (optional)
+    csv_opts = None
+    if args.csv_has_header or args.csv_meta_cols or args.csv_include_cols:
+        csv_opts = {
+            "has_header": args.csv_has_header or "auto", # "auto" | "yes" | "no"
+            "meta_cols": args.csv_meta_cols or "",       # "name1,name2" or "1,3"
+            "include_cols": args.csv_include_cols or "", # "nameA,2,5"
+        }
+
+    out = svc_ingest_document(
+        store, args.tenant, args.collection, args.file, content,
+        baseid if args.docid else None, meta, csv_options=csv_opts
+    )
+    print(json.dumps(out, ensure_ascii=False))
+
+def cmd_search(args):
+    filters = json.loads(args.filters) if args.filters else None
+    out = svc_do_search(store, args.tenant, args.collection, args.query, args.k, filters=filters)
+    print(json.dumps(out, ensure_ascii=False))
+
+def cmd_delete(args):
+    out = svc_delete_collection(store, args.tenant, args.collection)
+    print(json.dumps(out, ensure_ascii=False))
+
+def main_cli(argv=None):
+    p = argparse.ArgumentParser(prog="pavecli")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    #if p.config: reload_cfg(p.config)
+
+    p_create = sub.add_parser("create-collection")
+    p_create.add_argument("tenant")
+    p_create.add_argument("collection")
+    p_create.set_defaults(func=cmd_create)
+
+    p_upload = sub.add_parser("upload")
+    p_upload.add_argument("tenant")
+    p_upload.add_argument("collection")
+    p_upload.add_argument("file")
+    p_upload.add_argument("--docid")
+    p_upload.add_argument("--metadata")
+
+    # --- CSV controls ---
+    p_upload.add_argument("--csv-has-header", choices=["auto", "yes", "no"],
+                          help="CSV header handling: auto (sniff), yes, or no")
+    p_upload.add_argument("--csv-meta-cols",
+                          help="CSV columns to store as metadata only (exclude from text). Names or 1-based indices, comma-separated")
+    p_upload.add_argument("--csv-include-cols",
+                          help="CSV columns to include in indexed text. Names or 1-based indices, comma-separated. Defaults to all non-meta columns")
+
+    p_upload.set_defaults(func=cmd_upload)
+
+    p_search = sub.add_parser("search")
+    p_search.add_argument("tenant")
+    p_search.add_argument("collection")
+    p_search.add_argument("query")
+    p_search.add_argument("-k", type=int, default=5)
+    p_search.add_argument("--filters", help='JSON object, e.g. {"docid":"DOC-1"}')
+    p_search.set_defaults(func=cmd_search)
+
+    p_delete = sub.add_parser("delete-collection")
+    p_delete.add_argument("tenant")
+    p_delete.add_argument("collection")
+    p_delete.set_defaults(func=cmd_delete)
+
+    args = p.parse_args(argv)
+    return args.func(args)
+
+if __name__ == "__main__":
+    raise SystemExit(main_cli())