Metadata-Version: 2.4
Name: respan-instrumentation-pgvector
Version: 0.1.0
Summary: Respan instrumentation plugin for pgvector with psycopg
License: Apache 2.0
Author: Respan
Author-email: team@respan.ai
Requires-Python: >=3.11,<3.14
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Provides-Extra: psycopg2
Requires-Dist: opentelemetry-semantic-conventions-ai (>=0.4.1)
Requires-Dist: pgvector (>=0.3.0,<1.0.0)
Requires-Dist: psycopg2-binary (>=2.9.0,<3.0.0) ; extra == "psycopg2"
Requires-Dist: psycopg[binary] (>=3.1.0,<4.0.0)
Requires-Dist: respan-sdk (>=2.6.1)
Requires-Dist: respan-tracing (>=2.17.0,<3.0.0)
Requires-Dist: wrapt (>=1.16.0)
Description-Content-Type: text/markdown

# respan-instrumentation-pgvector

Respan instrumentation for pgvector applications using psycopg 3. It traces
sync and async pgvector type registration, connection/cursor execution,
executemany, and result fetching as canonical Respan task spans. Psycopg 2 type
registration is also detected when the optional `psycopg2` extra is installed.

## Install

```bash
pip install respan-ai respan-instrumentation-pgvector pgvector "psycopg[binary]"
```

For pgvector's psycopg 2 adapter:

```bash
pip install "respan-instrumentation-pgvector[psycopg2]"
```

## Quickstart

```python
import psycopg
import pgvector.psycopg as pgvector_psycopg
from respan import Respan, workflow
from respan_instrumentation_pgvector import PGVectorInstrumentor

respan = Respan(instrumentations=[PGVectorInstrumentor()])


@workflow(name="pgvector_similarity_query_workflow")
def run_query(dsn: str):
    with psycopg.connect(dsn) as connection:
        pgvector_psycopg.register_vector(connection)
        return connection.execute(
            "SELECT id, embedding FROM items ORDER BY embedding <-> %s LIMIT 3",
            ([0.1, 0.2, 0.3],),
        ).fetchall()


print(run_query("postgresql://localhost/postgres"))
respan.shutdown()
```

Pass `capture_content=False` to omit SQL arguments, parameters, and returned
rows while retaining operation names, status, and PostgreSQL attributes.
Activation/deactivation and `instrument()` / `uninstrument()` are idempotent.
SQLAlchemy applications that use the psycopg 3 driver are covered at the
underlying connection/cursor layer.

See `respan-example-projects/python/tracing/pgvector` for setup, distance
operators, sync/async, mutation, bulk insert, and deterministic error examples.

