an5-adapters 0.2.0__py3-none-any.whl

an5_adapter.py

@@ -0,0 +1,97 @@
+"""Standalone Python runtime adapter for AN5 ORM."""
+
+from typing import Dict, List, Optional
+
+try:
+    from .base import DIALECT_MSSQL, DIALECT_POSTGRES, detect_dialect, set_adapter_metadata
+    from .mssql import connect as connect_mssql
+    from .postgres import connect as connect_postgres
+    from .table_client import AdapterTableClient
+except ImportError:
+    from base import DIALECT_MSSQL, DIALECT_POSTGRES, detect_dialect, set_adapter_metadata
+    from mssql import connect as connect_mssql
+    from postgres import connect as connect_postgres
+    from table_client import AdapterTableClient
+
+# Backward-compatible aliases used by tests and older imports.
+_detect_dialect = detect_dialect
+try:
+    from .mssql import parse_connection_string as _parse_connection_string
+except ImportError:
+    from mssql import parse_connection_string as _parse_connection_string
+
+class An5Adapter:
+    def __init__(self, connection_string: str):
+        self._dialect = detect_dialect(connection_string)
+        self._conn_str = connection_string
+
+    def _connect(self):
+        if self._dialect == DIALECT_POSTGRES:
+            return connect_postgres(self._conn_str)
+        return connect_mssql(self._conn_str)
+
+    def _to_dicts(self, cursor, query: str) -> List[Dict]:
+        if cursor.description:
+            cols = [col[0] for col in cursor.description]
+            rows = cursor.fetchall() if cursor.description else []
+            return [dict(zip(cols, row)) for row in rows]
+        return []
+
+    def exec(self, query: str, params: Optional[List] = None) -> List[Dict]:
+        conn = self._connect()
+        try:
+            cursor = conn.cursor()
+            cursor.execute(query, params or [])
+            return self._to_dicts(cursor, query)
+        finally:
+            conn.close()
+
+    def execute(self, query: str, params: Optional[List] = None) -> int:
+        conn = self._connect()
+        try:
+            cursor = conn.cursor()
+            cursor.execute(query, params or [])
+            return cursor.rowcount
+        finally:
+            conn.close()
+
+    def query_raw(self, query: str, *values) -> List[Dict]:
+        return self.exec(query, list(values))
+
+    def execute_raw(self, query: str, *values) -> int:
+        return self.execute(query, list(values))
+
+    def table(self, model_name: str) -> AdapterTableClient:
+        return AdapterTableClient(self, model_name)
+
+    def __getattr__(self, model_name: str) -> AdapterTableClient:
+        return self.table(model_name)
+
+    def transaction(self, fn):
+        conn = self._connect()
+        conn.autocommit = False
+        try:
+            result = fn(self)
+            conn.commit()
+            return result
+        except Exception:
+            conn.rollback()
+            raise
+        finally:
+            if self._dialect == DIALECT_POSTGRES:
+                conn.autocommit = True
+            conn.close()
+
+def create_an5_adapter(connection_string: str) -> An5Adapter:
+    return An5Adapter(connection_string)
+
+__all__ = [
+    "An5Adapter",
+    "AdapterTableClient",
+    "create_an5_adapter",
+    "DIALECT_MSSQL",
+    "DIALECT_POSTGRES",
+    "_detect_dialect",
+    "_parse_connection_string",
+    "set_adapter_metadata",
+]

an5_adapters-0.2.0.dist-info/METADATA

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: an5-adapters
+Version: 0.2.0
+Summary: Python adapter helpers for AN5 ORM.
+Author: an5ORM
+License: MIT
+Keywords: an5,orm,adapter
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pyodbc>=5.0
+Requires-Dist: psycopg2-binary>=2.9
+
+# an5Adapters
+
+Standalone runtime adapters for AN5 ORM. Provides connection pooling, query execution, typed table clients in TypeScript, Python, .NET, and Google Sheets API.
+
+Adapters are runtime packages only. They do not import generated `an5Client` artifacts; generated clients or applications can pass model metadata explicitly when table-name mapping or field type coercion is needed.
+
+## Features
+
+- **Connection pooling** — Managed connection pools with configurable limits
+- **Type-safe table clients** — Generic CRUD operations with type inference
+- **Full query support** — WHERE, ORDER BY, pagination, aggregates
+- **Vector search** — Cosine, euclidean, and dot product similarity
+- **Transactions** — Begin/commit/rollback with automatic cleanup
+- **Cross-language** — Same API in TypeScript, Python, and .NET
+- **Google Sheets** — Use spreadsheets as a database with the same CRUD API
+
+## Installation
+
+### TypeScript
+
+```bash
+npm install an5-adapters
+```
+
+### Python
+
+```bash
+pip install an5-adapters
+```
+
+### .NET
+
+```bash
+dotnet add package An5Adapters
+```
+
+## Usage
+
+### TypeScript
+
+```typescript
+import { createAn5Adapter, setAdapterMetadata } from 'an5-adapters';
+
+setAdapterMetadata({
+  modelToTable: { User: 'dbo.users' },
+  modelFields: {
+    User: {
+      id: { ts: 'string', sql: 'uniqueidentifier', isId: true },
+      active: { ts: 'boolean', sql: 'bit' },
+    },
+  },
+});
+
+const db = createAn5Adapter({
+  connectionString: 'sqlserver://localhost:1433;database=mydb;user=sa;password=pass',
+});
+
+// Table client
+const users = db.table<User>('users');
+await users.findMany({ where: { active: true }, take: 10 });
+
+// Raw queries
+const rows = await db.exec('SELECT * FROM users WHERE id = @id', { id: '123' });
+
+// Transactions
+await db.$transaction(async (tx) => {
+  await tx.table('users').create({ data: { name: 'John' } });
+});
+```
+
+### Python
+
+```python
+from an5_adapter import create_an5_adapter
+from base.metadata import set_adapter_metadata
+
+set_adapter_metadata({
+    "modelToTable": {"User": "dbo.users"},
+    "modelFields": {
+        "User": {
+            "id": {"py": "str", "sql": "uniqueidentifier", "isId": True},
+            "active": {"py": "bool", "sql": "bit"},
+        }
+    },
+})
+
+db = create_an5_adapter("sqlserver://localhost:1433;database=mydb;user=sa;password=pass")
+
+# Table client
+users = db.table("User")
+users.find_many(where={"active": True}, take=10)
+
+# Raw queries
+rows = db.exec("SELECT * FROM users WHERE id = ?", params=["123"])
+
+# Transactions
+db.transaction(lambda tx: tx.table("User").create({"name": "John"}))
+```
+
+### .NET
+
+```csharp
+using An5Orm;
+
+var db = new An5Adapter(connectionString);
+
+// Table client
+var users = db.Table<User>("dbo.users");
+var activeUsers = users.FindMany("IsActive = @p", new { p = true });
+
+// Raw queries
+var rows = db.QueryRaw("SELECT * FROM users WHERE Id = @id", new { id = "123" });
+
+// Transactions
+db.Transaction(tx => {
+    tx.Table<User>("dbo.users").Create(new User { Name = "John" });
+});
+```
+
+### Google Sheets
+
+```typescript
+import { createAn5SheetsAdapter } from 'an5-adapters';
+
+const db = createAn5SheetsAdapter({
+  spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms',
+  // Option 1: client email + private key
+  clientEmail: 'sa@project.iam.gserviceaccount.com',
+  privateKey: '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----',
+  // Option 2: full service account JSON
+  // credentials: { client_email: '...', private_key: '...' },
+  // Optional: map model names to sheet names
+  sheetMapping: { users: 'UsersData', orders: 'OrdersData' },
+});
+
+// Table client (same API as SQL adapters)
+const users = db.table<User>('users');
+await users.findMany({ where: { active: true }, take: 10 });
+await users.create({ data: { name: 'John', email: 'john@example.com' } });
+await users.update({ where: { email: 'john@example.com' }, data: { name: 'Johnny' } });
+await users.delete({ where: { email: 'john@example.com' } });
+
+// Raw range access (Google Sheets specific)
+const rawData = await db.readRange('Sheet1!A1:C10');
+await db.writeRange('Sheet1!A1:B2', [['Name', 'Age'], ['Alice', '30']]);
+await db.appendRange('Sheet1!A:A', [['Bob', '25']]);
+
+// Auto-creates sheet + header row on first create()
+await db.table('orders').create({ data: { id: '1', total: 100 } });
+
+// List, delete sheets
+const sheets = await db.listSheets();
+await db.deleteSheet('OldSheet');
+
+// Clear data (keeps headers) or delete all rows
+await db.table('users').clear();
+await db.table('users').deleteAll();
+```
+
+### Integrated factory (auto-detect adapter)
+
+```typescript
+import { createAn5Adapter, createAdapter, An5Adapter } from 'an5-adapters';
+
+// Auto-detects from connection string
+const sqlDb = createAn5Adapter({ connectionString: 'sqlserver://localhost:1433;database=mydb;user=sa;password=pass' });
+
+const sheetsDb = createAn5Adapter({
+  connectionString: 'googlesheets://spreadsheetId;clientEmail=sa@project.iam.gserviceaccount.com;privateKey=...',
+});
+
+// Or use the Sheets config object directly (also auto-detected)
+const sheetsDb2 = createAdapter({
+  spreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms',
+  clientEmail: 'sa@project.iam.gserviceaccount.com',
+  privateKey: '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----',
+});
+
+// Constructor form also delegates googlesheets:// to the Sheets adapter
+const sheetsDb3 = new An5Adapter({
+  connectionString: 'googlesheets://spreadsheetId;clientEmail=sa@project.iam.gserviceaccount.com;privateKey=...',
+});
+```
+
+**Notes:**
+- Each model/table maps to a **sheet tab** (first row = headers)
+- Sheets without header rows get auto-created on first `create()`
+- Type coercion can use optional adapter metadata (`setAdapterMetadata`) for field types and model-to-table mapping
+- Numeric strings (without leading zeros) are auto-coerced; `"00123"` stays string
+- Boolean strings `"true"` / `"false"` are auto-coerced
+- Sheet names with spaces are automatically escaped (A1 notation)
+- Supports service account JSON or individual `clientEmail`+`privateKey`
+- Automatic retry with exponential backoff for rate limits (429/500/503)
+
+### Provider Imports
+
+Use the package root for normal applications:
+
+```typescript
+import { createAn5Adapter, createAn5SheetsAdapter } from 'an5-adapters';
+```
+
+Provider folders are still available to source-level consumers through `typescript/*`, but the public factory in `typescript/an5Adapter.ts` is the preferred entry point. The old `unified.ts` entry point has been removed because the factory now lives directly in `An5Adapter`.
+
+## API Reference
+
+### An5Adapter / An5SheetsAdapter
+
+| Method | Description |
+|--------|-------------|
+| `exec(query, params)` | Execute query, return rows (SQL only) |
+| `table<T>(name)` | Get typed table client |
+| `$transaction(fn)` | Execute in transaction |
+| `$connect()` | Open connection / authenticate |
+| `$disconnect()` | Close connection / clear auth |
+| `readRange(range)` | Read raw sheet range (Sheets only) |
+| `writeRange(range, values)` | Write raw sheet range (Sheets only) |
+| `appendRange(range, values)` | Append rows to sheet (Sheets only) |
+| `listSheets()` | List all sheet tab names (Sheets only) |
+| `deleteSheet(name)` | Delete a sheet tab (Sheets only) |
+
+### AdapterTableClient / SheetsTableClient
+
+| Method | Description |
+|--------|-------------|
+| `findMany(args)` | Query multiple rows |
+| `findFirst(args)` | Query single row |
+| `findUnique(where)` | Find by unique key |
+| `count(where)` | Count rows |
+| `create(data)` | Insert row |
+| `createMany(data)` | Bulk insert |
+| `update(where, data)` | Update row |
+| `updateMany(where, data)` | Update multiple rows |
+| `delete(where)` | Delete row |
+| `deleteMany(where)` | Delete multiple rows |
+| `upsert(where, create, update)` | Insert or update |
+| `aggregate(args)` | SUM, AVG, MIN, MAX, COUNT |
+| `groupBy(args)` | Group by fields |
+| `vectorSearch(args)` | Semantic similarity search |
+| `clear()` | Clear all data rows, keep headers (Sheets only) |
+| `deleteAll()` | Delete all data rows including headers (Sheets only) |
+
+## Provider Layout
+
+- TypeScript providers live under `typescript/{base,mssql,postgres,mysql,sqlite,googlesheets}`.
+- Python providers live under `python/{base,mssql,postgres}`, with `python/an5_adapter.py` kept as the public facade.
+- .NET providers live under `dotnet/{Base,Mssql,Postgres}`, with `dotnet/an5Adapter.cs` kept as the public facade.
+- Adapters do not depend on generated `an5-client` artifacts; generated clients may pass metadata in explicitly when they need model/table mapping.
+
+## Testing
+
+```bash
+# TypeScript/Node
+node test/unit.test.js
+
+# Python
+python -m compileall python
+python test/smoke.py
+```
+
+## License
+
+MIT

an5_adapters-0.2.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+an5_adapter.py,sha256=4inAATh5FdShLWJv77RDdh0DPAf2Mx-4lcDOfTXrfqM,3215
+table_client.py,sha256=5rLF3U5p8vPyc3pngZjDQE0zRN71ppoaIQZeSx0LJAA,9188
+base/__init__.py,sha256=ttdMZrFMwrkPeegf-LoeLWXIIott-LtFfKSz_wRmCPI,228
+base/dialects.py,sha256=j-aDD0pBMIOEFXpaxtJ0HykEatF6VUbEYkdbLT5gzj8,277
+base/metadata.py,sha256=ozEwwQi9vR1W1ORzS-ipckz908P5d6I9olFSug0hcX0,400
+base/sql.py,sha256=rAmaHM3eu5whnaL9quDb461i9gq8iHQX8b2xk2spJ70,5563
+mssql/__init__.py,sha256=ipc1F1Or3Rn2JRM2_Zmtx2yixQ89id0kPPfIgtNbkrs,86
+mssql/provider.py,sha256=QMWZey674W9u60n2oURuLySQSzxfKaAJ0Thipa8Sn-8,2054
+postgres/__init__.py,sha256=ldDHixTERLgs8ieOIdidzyCzfNzzwuCbz9JjWhMMfOA,63
+postgres/provider.py,sha256=gldk1MiVnXzR5_7jmtuNtWUZghyuPpyPIN6sRfgOw1Y,391
+an5_adapters-0.2.0.dist-info/METADATA,sha256=P4QqTqEO-Wwg1-7Fk1WK0Po6n-BtfevWa7CYF9ZVgJ0,9092
+an5_adapters-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+an5_adapters-0.2.0.dist-info/top_level.txt,sha256=cdCq2J7feHvCYWx440osNWpRHHBtYsuMCkXTYRQ8ZQ0,45
+an5_adapters-0.2.0.dist-info/RECORD,,

an5_adapters-0.2.0.dist-info/WHEEL

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

an5_adapters-0.2.0.dist-info/top_level.txt

@@ -0,0 +1,5 @@
+an5_adapter
+base
+mssql
+postgres
+table_client

base/__init__.py

@@ -0,0 +1,3 @@
+from .dialects import DIALECT_MSSQL, DIALECT_POSTGRES, detect_dialect
+from .metadata import model_to_table, model_fields, set_adapter_metadata
+from .sql import _quote, _parse_where, _build_order_by, _resolve_table, _quote_table

base/dialects.py

@@ -0,0 +1,8 @@
+DIALECT_MSSQL = "mssql"
+DIALECT_POSTGRES = "postgres"
+
+def detect_dialect(connection_string: str) -> str:
+    cs = connection_string.strip().lower()
+    if cs.startswith("postgres://") or cs.startswith("postgresql://"):
+        return DIALECT_POSTGRES
+    return DIALECT_MSSQL

base/metadata.py

@@ -0,0 +1,10 @@
+from typing import Any, Dict
+
+model_to_table: Dict[str, str] = {}
+model_fields: Dict[str, Any] = {}
+
+def set_adapter_metadata(metadata: Dict[str, Any]) -> None:
+    model_to_table.clear()
+    model_to_table.update(metadata.get("model_to_table") or metadata.get("modelToTable") or {})
+    model_fields.clear()
+    model_fields.update(metadata.get("model_fields") or metadata.get("modelFields") or {})

base/sql.py

@@ -0,0 +1,121 @@
+from typing import Any, Dict, List, Optional
+from .dialects import DIALECT_MSSQL, DIALECT_POSTGRES
+from .metadata import model_to_table, model_fields
+
+# ─── Quoting ───────────────────────────────────────────────────────────────────────
+
+def _quote(name: str, dialect: str) -> str:
+    if dialect == DIALECT_POSTGRES:
+        if name.startswith("[") and name.endswith("]"):
+            return f'"{name[1:-1]}"'
+        return f'"{name}"'
+    return name if name.startswith("[") else f"[{name}]"
+
+
+# ─── Connection helpers live in provider modules ────────────────────────────────
+
+# ─── Where clause builder ──────────────────────────────────────────────────────────
+
+def _parse_where(model_name: str, where: Optional[Dict], params: Dict, dialect: str, prefix: str = "") -> str:
+    if not where:
+        return ""
+    conditions: List[str] = []
+
+    for key, value in where.items():
+        if key == "OR" and isinstance(value, list):
+            sub = [_parse_where(model_name, v, params, dialect, f"{prefix}or{i}_") for i, v in enumerate(value)]
+            sub = [s for s in sub if s]
+            if sub:
+                conditions.append(f"({' OR '.join(sub)})")
+        elif key == "AND" and isinstance(value, list):
+            sub = [_parse_where(model_name, v, params, dialect, f"{prefix}and{i}_") for i, v in enumerate(value)]
+            sub = [s for s in sub if s]
+            if sub:
+                conditions.append(f"({' AND '.join(sub)})")
+        else:
+            col = _quote(key, dialect)
+            pname = f"{prefix}{key}"
+            placeholder = "%s" if dialect == DIALECT_POSTGRES else "?"
+            if value is None:
+                conditions.append(f"{col} IS NULL")
+            elif isinstance(value, dict):
+                if "not" in value:
+                    if value["not"] is None:
+                        conditions.append(f"{col} IS NOT NULL")
+                    else:
+                        params[f"{pname}_not"] = value["not"]
+                        conditions.append(f"{col} <> {placeholder}")
+                if "equals" in value:
+                    params[f"{pname}_eq"] = value["equals"]
+                    conditions.append(f"{col} = {placeholder}")
+                if "contains" in value:
+                    params[f"{pname}_co"] = f"%{value['contains']}%"
+                    conditions.append(f"{col} LIKE {placeholder}")
+                if "startsWith" in value:
+                    params[f"{pname}_sw"] = f"{value['startsWith']}%"
+                    conditions.append(f"{col} LIKE {placeholder}")
+                if "endsWith" in value:
+                    params[f"{pname}_ew"] = f"%{value['endsWith']}"
+                    conditions.append(f"{col} LIKE {placeholder}")
+                if "gte" in value:
+                    params[f"{pname}_gte"] = value["gte"]
+                    conditions.append(f"{col} >= {placeholder}")
+                if "lte" in value:
+                    params[f"{pname}_lte"] = value["lte"]
+                    conditions.append(f"{col} <= {placeholder}")
+                if "gt" in value:
+                    params[f"{pname}_gt"] = value["gt"]
+                    conditions.append(f"{col} > {placeholder}")
+                if "lt" in value:
+                    params[f"{pname}_lt"] = value["lt"]
+                    conditions.append(f"{col} < {placeholder}")
+                if "in" in value:
+                    vals = value["in"]
+                    if vals:
+                        placeholders = ", ".join([placeholder] * len(vals))
+                        for i, v in enumerate(vals):
+                            params[f"{pname}_in{i}"] = v
+                        conditions.append(f"{col} IN ({placeholders})")
+                    else:
+                        conditions.append("1=0")
+            else:
+                params[pname] = value
+                conditions.append(f"{col} = {placeholder}")
+
+    return " AND ".join(conditions)
+
+
+def _build_order_by(order_by: Any, dialect: str) -> str:
+    if not order_by:
+        return ""
+    entries = order_by if isinstance(order_by, list) else [order_by]
+    parts: List[str] = []
+    for entry in entries:
+        for col, direction in entry.items():
+            parts.append(f"{_quote(col, dialect)} {str(direction).upper()}")
+    return f"ORDER BY {', '.join(parts)}" if parts else ""
+
+
+# ─── Table name resolution ─────────────────────────────────────────────────────────
+
+def _resolve_table(model_name: str) -> str:
+    if model_name in model_to_table:
+        return model_to_table[model_name]
+    camel = model_name[0].lower() + model_name[1:] if model_name else model_name
+    if camel in model_to_table:
+        return model_to_table[camel]
+    lower = model_name.lower()
+    if lower in model_to_table:
+        return model_to_table[lower]
+    return model_name
+
+
+def _quote_table(t: str, dialect: str) -> str:
+    q = lambda s: f'"{s}"' if dialect == DIALECT_POSTGRES else f"[{s}]"
+    if t.startswith("[") or t.startswith('"'):
+        return t
+    if "." in t:
+        return ".".join(q(p) for p in t.split("."))
+    return q(t)
+
+

mssql/__init__.py

@@ -0,0 +1 @@
+from .provider import PYODBC_AVAILABLE, connect, parse_connection_string, placeholder

mssql/provider.py

@@ -0,0 +1,62 @@
+try:
+    import pyodbc
+    PYODBC_AVAILABLE = True
+except ImportError:
+    pyodbc = None
+    PYODBC_AVAILABLE = False
+
+def parse_connection_string(url: str) -> str:
+    """Convert sqlserver:// URL to pyodbc connection string."""
+    url = url.replace("sqlserver://", "")
+    parts = url.split(";")
+    host_part = parts[0]
+    host, _, port = host_part.partition(":")
+    port = port or "1433"
+
+    config: Dict[str, str] = {"server": host, "port": port}
+    for part in parts[1:]:
+        if "=" not in part:
+            continue
+        k, _, v = part.partition("=")
+        k = k.strip().lower()
+        v = v.strip()
+        if k in ("database",):
+            config["database"] = v
+        elif k in ("user", "uid"):
+            config["user"] = v
+        elif k in ("password", "pwd"):
+            config["password"] = v
+        elif k == "encrypt":
+            config["encrypt"] = "yes" if v.lower() == "true" else "no"
+        elif k == "trustservercertificate":
+            config["trust"] = "yes" if v.lower() == "true" else "no"
+
+    encrypt = config.get("encrypt", "yes")
+    trust = config.get("trust", "yes")
+    if "user" in config:
+        return (
+            f"DRIVER={{ODBC Driver 17 for SQL Server}};"
+            f"SERVER={config['server']},{config['port']};"
+            f"DATABASE={config.get('database', '')};"
+            f"UID={config['user']};"
+            f"PWD={config.get('password', '')};"
+            f"Encrypt={encrypt};TrustServerCertificate={trust};"
+        )
+    # Windows auth
+    return (
+        f"DRIVER={{ODBC Driver 17 for SQL Server}};"
+        f"SERVER={config['server']},{config['port']};"
+        f"DATABASE={config.get('database', '')};"
+        f"Trusted_Connection=yes;"
+        f"Encrypt={encrypt};TrustServerCertificate={trust};"
+    )
+
+
+
+def connect(connection_string: str):
+    if not PYODBC_AVAILABLE:
+        raise ImportError("pyodbc is required: pip install pyodbc")
+    return pyodbc.connect(parse_connection_string(connection_string), autocommit=True)
+
+def placeholder() -> str:
+    return "?"

postgres/__init__.py

@@ -0,0 +1 @@
+from .provider import PSYCOPG2_AVAILABLE, connect, placeholder

postgres/provider.py

@@ -0,0 +1,15 @@
+try:
+    import psycopg2
+    import psycopg2.extras
+    PSYCOPG2_AVAILABLE = True
+except ImportError:
+    psycopg2 = None
+    PSYCOPG2_AVAILABLE = False
+
+def connect(connection_string: str):
+    if not PSYCOPG2_AVAILABLE:
+        raise ImportError("psycopg2 is required: pip install psycopg2-binary")
+    return psycopg2.connect(connection_string)
+
+def placeholder() -> str:
+    return "%s"

table_client.py

@@ -0,0 +1,216 @@
+import json
+import uuid
+from typing import Dict, List, Optional
+try:
+    from .base import DIALECT_MSSQL, DIALECT_POSTGRES, model_fields, _build_order_by, _parse_where, _quote, _quote_table, _resolve_table
+except ImportError:
+    from base import DIALECT_MSSQL, DIALECT_POSTGRES, model_fields, _build_order_by, _parse_where, _quote, _quote_table, _resolve_table
+
+# ─── Table Client ───────────────────────────────────────────────────────────────────
+
+class AdapterTableClient:
+    def __init__(self, adapter: An5Adapter, model_name: str):
+        self._adapter = adapter
+        self._model = model_name
+        self._dialect = adapter._dialect
+
+    @property
+    def _table(self) -> str:
+        return _resolve_table(self._model)
+
+    @property
+    def _table_sql(self) -> str:
+        return _quote_table(self._table, self._dialect)
+
+    @property
+    def _nolock(self) -> str:
+        return "" if self._dialect == DIALECT_POSTGRES else " WITH (NOLOCK)"
+
+    @property
+    def _fields(self) -> List[Dict]:
+        fields = model_fields.get(self._model, [])
+        if isinstance(fields, dict):
+            raise TypeError(
+                "AN5 Python metadata is out of date. Regenerate with @an5/orm >= 1.0.4 "
+                "so MODEL_FIELDS uses a list of field objects."
+            )
+        return fields
+
+    def _pagination(self, take: Optional[int], skip: int, order_sql: str) -> str:
+        if take is None:
+            return ""
+        if self._dialect == DIALECT_POSTGRES:
+            return f" LIMIT {take} OFFSET {skip}"
+        order_prefix = "" if order_sql else " ORDER BY (SELECT NULL)"
+        return f"{order_prefix} OFFSET {skip} ROWS FETCH NEXT {take} ROWS ONLY"
+
+    def find_many(self, where=None, order_by=None, skip: int = 0, take: Optional[int] = None, select=None) -> List[Dict]:
+        params: Dict = {}
+        where_sql = _parse_where(self._model, where, params, self._dialect)
+        order_sql = _build_order_by(order_by, self._dialect)
+
+        query = f"SELECT * FROM {self._table_sql}{self._nolock}"
+        if where_sql:
+            query += f" WHERE {where_sql}"
+        if order_sql:
+            query += f" {order_sql}"
+        query += self._pagination(take, skip, order_sql)
+        return self._adapter.exec(query, list(params.values()))
+
+    def find_first(self, where=None, order_by=None, select=None) -> Optional[Dict]:
+        rows = self.find_many(where=where, order_by=order_by, take=1, select=select)
+        return rows[0] if rows else None
+
+    def find_unique(self, where: Dict) -> Optional[Dict]:
+        return self.find_first(where=where)
+
+    def count(self, where=None) -> int:
+        params: Dict = {}
+        where_sql = _parse_where(self._model, where, params, self._dialect)
+        query = f"SELECT COUNT(*) AS cnt FROM {self._table_sql}{self._nolock}"
+        if where_sql:
+            query += f" WHERE {where_sql}"
+        rows = self._adapter.exec(query, list(params.values()))
+        return int(rows[0]["cnt"]) if rows else 0
+
+    def create(self, data: Dict) -> Dict:
+        id_field = next((f for f in self._fields if f.get("isId")), None)
+        if id_field and id_field["name"] not in data:
+            data = {**data, id_field["name"]: str(uuid.uuid4())}
+
+        cols = [k for k, v in data.items() if v is not None]
+        values = [data[c] for c in cols]
+        placeholders = ", ".join(["?" if self._dialect == DIALECT_MSSQL else "%s"] * len(cols))
+        col_list = ", ".join(_quote(c, self._dialect) for c in cols)
+        query = f"INSERT INTO {self._table_sql} ({col_list}) VALUES ({placeholders})"
+        self._adapter.execute(query, values)
+
+        if id_field:
+            return self.find_first(where={id_field["name"]: data[id_field["name"]]}) or data
+        return data
+
+    def create_many(self, data: List[Dict], skip_duplicates: bool = False) -> Dict:
+        count = 0
+        for row in data:
+            try:
+                self.create(row)
+                count += 1
+            except Exception:
+                if not skip_duplicates:
+                    raise
+        return {"count": count}
+
+    def update(self, where: Dict, data: Dict) -> Optional[Dict]:
+        params: Dict = {}
+        where_sql = _parse_where(self._model, where, params, self._dialect, "w_")
+        set_parts: List[str] = []
+        set_values: List = []
+        placeholder = "?" if self._dialect == DIALECT_MSSQL else "%s"
+        for col, val in data.items():
+            if val is not None:
+                set_parts.append(f"{_quote(col, self._dialect)} = {placeholder}")
+                set_values.append(val)
+
+        all_values = set_values + list(params.values())
+        query = f"UPDATE {self._table_sql} SET {', '.join(set_parts)}"
+        if where_sql:
+            query += f" WHERE {where_sql}"
+        self._adapter.execute(query, all_values)
+        return self.find_first(where=where)
+
+    def update_many(self, where: Optional[Dict], data: Dict) -> Dict:
+        params: Dict = {}
+        where_sql = _parse_where(self._model, where, params, self._dialect, "w_")
+        set_parts: List[str] = []
+        set_values: List = []
+        placeholder = "?" if self._dialect == DIALECT_MSSQL else "%s"
+        for col, val in data.items():
+            set_parts.append(f"{_quote(col, self._dialect)} = {placeholder}")
+            set_values.append(val)
+        all_values = set_values + list(params.values())
+        query = f"UPDATE {self._table_sql} SET {', '.join(set_parts)}"
+        if where_sql:
+            query += f" WHERE {where_sql}"
+        count = self._adapter.execute(query, all_values)
+        return {"count": count}
+
+    def delete(self, where: Dict) -> Optional[Dict]:
+        existing = self.find_first(where=where)
+        params: Dict = {}
+        where_sql = _parse_where(self._model, where, params, self._dialect)
+        query = f"DELETE FROM {self._table_sql} WHERE {where_sql}"
+        self._adapter.execute(query, list(params.values()))
+        return existing
+
+    def delete_many(self, where: Optional[Dict] = None) -> Dict:
+        params: Dict = {}
+        where_sql = _parse_where(self._model, where, params, self._dialect)
+        query = f"DELETE FROM {self._table_sql}"
+        if where_sql:
+            query += f" WHERE {where_sql}"
+        count = self._adapter.execute(query, list(params.values()))
+        return {"count": count}
+
+    def upsert(self, where: Dict, create: Dict, update: Dict) -> Dict:
+        existing = self.find_first(where=where)
+        if existing:
+            return self.update(where=where, data=update) or existing
+        return self.create(data=create)
+
+    def aggregate(self, where=None, _count=None, _sum=None, _avg=None, _min=None, _max=None) -> Dict:
+        params: Dict = {}
+        where_sql = _parse_where(self._model, where, params, self._dialect)
+        aggs: List[str] = []
+        if _count:
+            aggs.append("COUNT(*) AS _count")
+        if _sum:
+            for f in (_sum if isinstance(_sum, list) else [_sum]):
+                aggs.append(f"SUM({_quote(f, self._dialect)}) AS _sum_{f}")
+        if _avg:
+            for f in (_avg if isinstance(_avg, list) else [_avg]):
+                aggs.append(f"AVG({_quote(f, self._dialect)}) AS _avg_{f}")
+        if _min:
+            for f in (_min if isinstance(_min, list) else [_min]):
+                aggs.append(f"MIN({_quote(f, self._dialect)}) AS _min_{f}")
+        if _max:
+            for f in (_max if isinstance(_max, list) else [_max]):
+                aggs.append(f"MAX({_quote(f, self._dialect)}) AS _max_{f}")
+        if not aggs:
+            aggs = ["COUNT(*) AS _count"]
+
+        query = f"SELECT {', '.join(aggs)} FROM {self._table_sql}"
+        if where_sql:
+            query += f" WHERE {where_sql}"
+        rows = self._adapter.exec(query, list(params.values()))
+        return rows[0] if rows else {}
+
+    def vector_search(self, vector: List[float], take: int = 10, where=None, vector_field: str = "embedding", distance_metric: str = "cosine") -> List[Dict]:
+        rows = self.find_many(where=where)
+        scored = []
+        for row in rows:
+            raw = row.get(vector_field)
+            if raw is None:
+                continue
+            try:
+                vec = json.loads(raw) if isinstance(raw, str) else list(raw)
+            except Exception:
+                continue
+            if not vec or len(vec) != len(vector):
+                continue
+
+            dot = sum(a * b for a, b in zip(vector, vec))
+            m1 = sum(a ** 2 for a in vector) ** 0.5
+            m2 = sum(b ** 2 for b in vec) ** 0.5
+            cosine = dot / (m1 * m2) if m1 and m2 else 0.0
+
+            if distance_metric == "cosine":
+                dist = 1.0 - cosine
+            elif distance_metric == "dot":
+                dist = -dot
+            else:
+                dist = sum((a - b) ** 2 for a, b in zip(vector, vec)) ** 0.5
+
+            scored.append((row, dist))
+
+        scored.sort(key=lambda x: x[1])
+        return [{**row, "distance": dist} for row, dist in scored[:take]]