aura-connector 0.1.0__tar.gz

aura_connector-0.1.0/.gitignore

@@ -0,0 +1,63 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+*.egg-info/
+.eggs/
+.venv/
+venv/
+env/
+.tox/
+.nox/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Build and packaging
+build/
+dist/
+wheelhouse/
+site/
+*.whl
+*.tar.gz
+
+# Rust
+target/
+crates/*/target/
+
+# Maturin
+.maturin/
+*.profraw
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Secrets and local config
+.env
+.env.*
+*.pem
+*.key
+*.crt
+*.p12
+*.pfx
+
+# Logs
+*.log
+logs/
+
+# Local release artifacts
+.local/
+release/
+
+# Keep the native crate lockfile tracked for reproducible builds.
+!crates/aura_native/Cargo.lock

aura_connector-0.1.0/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
+project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-04
+
+Initial public release.
+
+### Added
+
+- Async-native client with connection lifecycle, context-manager usage, DSN parsing,
+  timeouts, retry policy, pooling abstraction, health check, and ping.
+- Typed model system with primary keys, optional fields, defaults and default factories,
+  nested models, list and document fields, relationships, and first-class vector fields.
+- Field system with `primary_key`, `unique`, `index`, defaults, aliases, descriptions,
+  metadata, and relationship and vector hints.
+- Fluent, injection-safe query builder that compiles to an immutable AST and Query IR,
+  covering find, filter, order, limit, offset, include, select, insert, bulk insert,
+  update, delete, upsert, count, exists, vector nearest-neighbour search, and a bounded
+  raw-statement escape hatch.
+- Deterministic binary wire protocol with framing, opcodes, flags, checksums, and length
+  limits, covered by golden byte tests.
+- Transport abstraction with a TCP transport and an in-memory reference server.
+- Result hydration into typed model instances, including relationships and vectors.
+- Schema generation and local migration diffing with a destructive-change CI gate.
+- In-process observability: per-operation metrics, latency percentiles, secret-free query
+  fingerprints, and an optional OpenTelemetry span bridge.
+- Command-line interface for offline, server-independent tasks.
+- Optional in-repository Rust/PyO3 native acceleration with a pure-Python fallback that is
+  always available.
+
+[Unreleased]: https://github.com/Ohswedd/aura-connector/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Ohswedd/aura-connector/releases/tag/v0.1.0

aura_connector-0.1.0/LICENSE

@@ -0,0 +1,19 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+   Copyright 2026 Aura Maintainers
+
+   Full license text: http://www.apache.org/licenses/LICENSE-2.0

aura_connector-0.1.0/PKG-INFO

@@ -0,0 +1,372 @@
+Metadata-Version: 2.4
+Name: aura-connector
+Version: 0.1.0
+Summary: Async-native, type-safe Python client and connector for AuraDB.
+Project-URL: Homepage, https://github.com/Ohswedd/aura-connector
+Project-URL: Documentation, https://github.com/Ohswedd/aura-connector/tree/main/docs
+Project-URL: Source, https://github.com/Ohswedd/aura-connector
+Project-URL: Issues, https://github.com/Ohswedd/aura-connector/issues
+Project-URL: Changelog, https://github.com/Ohswedd/aura-connector/blob/main/CHANGELOG.md
+Author: Aura Maintainers
+License: Apache-2.0
+License-File: LICENSE
+Keywords: async,auradb,client,connector,database,orm,vector
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: native
+Requires-Dist: maturin<2.0,>=1.5; extra == 'native'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# Aura Connector
+
+**Async-native, type-safe Python client and connector for AuraDB.**
+
+[![CI](https://github.com/Ohswedd/aura-connector/actions/workflows/ci.yml/badge.svg)](https://github.com/Ohswedd/aura-connector/actions/workflows/ci.yml)
+[![Native](https://github.com/Ohswedd/aura-connector/actions/workflows/native.yml/badge.svg)](https://github.com/Ohswedd/aura-connector/actions/workflows/native.yml)
+[![PyPI](https://img.shields.io/pypi/v/aura-connector.svg)](https://pypi.org/project/aura-connector/)
+[![Python](https://img.shields.io/pypi/pyversions/aura-connector.svg)](https://pypi.org/project/aura-connector/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Typed](https://img.shields.io/badge/typed-mypy%20strict-blue.svg)](https://mypy-lang.org/)
+[![Ruff](https://img.shields.io/badge/lint-ruff-261230.svg)](https://github.com/astral-sh/ruff)
+
+</div>
+
+Aura Connector gives Python teams ORM-level productivity with driver-level control.
+Declare typed models once, compose queries with a fluent, injection-safe builder, and
+execute relational, document, vector, hybrid, and graph workloads through a single async
+client over a deterministic binary wire protocol.
+
+It is useful today: the package ships an in-memory reference server and a complete
+pure-Python core, so the examples and the full test suite run with no external database
+and no compiler.
+
+```python
+import asyncio
+from aura import Aura, Model, Field, Vector
+
+
+class Workspace(Model):
+    id: int = Field(primary_key=True)
+    name: str
+
+
+class Document(Model):
+    id: int = Field(primary_key=True)
+    workspace: Workspace = Field(link=True)
+    title: str
+    body: str
+    embedding: Vector[3]
+
+
+async def main() -> None:
+    async with Aura.connect(
+        "aura+memory://localhost/app", models=[Workspace, Document]
+    ) as client:
+        ws = await client.insert(Workspace(id=1, name="Acme"))
+        await client.bulk_insert(
+            Document,
+            [
+                Document(id=1, workspace=ws, title="Refunds", body="...", embedding=[1, 0, 0]),
+                Document(id=2, workspace=ws, title="Billing", body="...", embedding=[0, 1, 0]),
+            ],
+        )
+
+        # Typed, injection-safe query building.
+        docs = await (
+            client.query(Document)
+            .where(Document.title.contains("Refund"))
+            .order_by(Document.id.desc())
+            .limit(10)
+            .all()
+        )
+
+        # Vector nearest-neighbour search.
+        matches = await (
+            client.search(Document)
+            .nearest(Document.embedding, [1, 0, 0], metric="cosine")
+            .limit(5)
+            .all()
+        )
+        print(docs, matches)
+
+
+asyncio.run(main())
+```
+
+## Why Aura Connector matters
+
+Python data access usually forces a trade. ORMs give you typed models and ergonomics but
+hide the wire and leak lazy queries. Raw drivers give you control but hand back untyped
+tuples and string SQL. Vector search lives in yet another SDK with its own client. Aura
+Connector unifies these behind one typed, async client:
+
+- **One typed client** for relational, document, vector, hybrid, and graph access.
+- **Async-first.** `asyncio` is the primary execution model, not a wrapper.
+- **Explicit relationship loading.** No hidden lazy network IO. `.include()` is required,
+  and accessing an unloaded relationship raises a clear error.
+- **Injection-safe by construction.** Queries compile to an immutable AST and Query IR,
+  never to concatenated strings.
+- **Deterministic binary protocol.** Frames are golden-tested, length-bounded, and
+  checksummed.
+- **Honest performance.** A complete pure-Python core with reproducible benchmarks, plus
+  optional in-repository native acceleration with a fallback that is always available.
+
+## Problems it solves
+
+- Replaces three separate libraries (ORM, driver, vector SDK) with one typed surface.
+- Removes the N+1 surprise by making relationship loading explicit.
+- Keeps queries safe without forcing you to hand-write parameter binding.
+- Makes schema changes reviewable: diff two model versions into a migration plan and gate
+  destructive changes in CI before anything runs.
+- Gives you metrics, latency percentiles, and secret-free query fingerprints in-process,
+  with an optional OpenTelemetry bridge.
+
+## How it compares
+
+| Tool | Typed models | Async-native | Injection-safe builder | Vector fields | Wire protocol control |
+|---|---|---|---|---|---|
+| SQLAlchemy | yes | partial | yes | via extensions | abstracted |
+| Django ORM | yes | partial | yes | via extensions | abstracted |
+| psycopg / asyncpg | no | yes (asyncpg) | manual binding | no | low level |
+| Prisma-style clients | yes | yes | yes | partial | abstracted |
+| Vector database SDKs | partial | varies | no | yes | per vendor |
+| **Aura Connector** | yes | yes | yes | first-class | deterministic, documented |
+
+The comparison describes design focus, not a benchmark. Each tool above is excellent at
+its own goals.
+
+## What Aura Connector is and is not
+
+It **is** a production-grade client and connector: model system, query builder, binary
+protocol, transports, hydration, migrations tooling, observability, and a CLI, with a
+pure-Python core and optional native acceleration.
+
+It is **not** a database server. AuraDB server features (storage, distributed
+transactions, server-side cost-based planning, lock and impact estimation on a live
+cluster) live in a separate project and are not implemented or claimed here. See
+[AuraDB boundary](docs/AURADB_BOUNDARY.md).
+
+## Installation
+
+```bash
+pip install aura-connector                 # pure-Python, always works, no compiler
+pip install "aura-connector[native]"       # + optional native acceleration tooling
+```
+
+The import package name is `aura`:
+
+```python
+import aura
+```
+
+Development install from a clone:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+Requires Python 3.11 or newer. The pure-Python path needs no compiler. Optional native
+acceleration (CRC32 plus f32 vector packing) lives in this repository under
+`crates/aura_native` and is built with maturin (requires a Rust toolchain):
+
+```bash
+maturin develop --manifest-path crates/aura_native/Cargo.toml --release
+aura doctor   # native_acceleration: available
+```
+
+See [Native acceleration](docs/NATIVE_ACCELERATION.md).
+
+## Quick start
+
+Aura uses `aura://` DSNs:
+
+| Scheme | Meaning |
+|---|---|
+| `aura://host:port/db` | Plaintext TCP |
+| `auras://host:port/db` | TLS TCP |
+| `aura+tcp://...` | Explicit TCP |
+| `aura+memory://...` | In-memory reference server (tests, examples, local dev) |
+
+The in-memory reference server is a real implementation of the protocol and a query
+engine, so no live AuraDB cluster is required to run the examples or the test suite.
+
+```python
+async with Aura.connect("aura+memory://localhost/app", models=[User]) as client:
+    await client.ping()
+```
+
+## Model example
+
+```python
+from aura import Model, Field, Vector
+
+
+class User(Model):
+    id: int = Field(primary_key=True)
+    email: str = Field(unique=True, index=True)
+    display_name: str | None = Field(default=None)
+    embedding: Vector[512] | None = None
+```
+
+## Query example
+
+```python
+cheap = await (
+    client.query(Product)
+    .where(Product.price_cents < 5000)
+    .order_by(Product.price_cents.asc())
+    .all()
+)
+
+await client.update(Product).where(Product.id == 2).set(price_cents=2499).execute()
+
+total = await client.query(Product).count()
+exists = await client.query(Product).where(Product.id == 3).exists()
+```
+
+## Vector example
+
+```python
+matches = await (
+    client.search(Document)
+    .nearest(Document.embedding, query_vector, metric="cosine")
+    .limit(10)
+    .all()
+)
+```
+
+Supported metrics are `cosine`, `euclidean`, and `dot`. See [Vectors](docs/VECTORS.md).
+
+## Migration example
+
+```python
+from aura import diff_schemas, generate_migration, schema_document
+
+plan = generate_migration(old_models, new_models)
+print(plan.format())
+plan.require_safe()   # raises AuraMigrationError if the plan is destructive
+```
+
+The same gate is available in CI through `aura migrate diff --require-safe`. See
+[Migrations](docs/MIGRATIONS.md).
+
+## Observability example
+
+```python
+async with Client.connect(
+    "aura+memory://localhost/shop",
+    models=[Product],
+    telemetry={"opentelemetry": True, "capture_query_ir": "redacted"},
+) as client:
+    await client.query(Product).filter(Product.price_cents > 500).all()
+    snapshot = client.metrics.snapshot()   # counts, latency p50/p95/p99, bytes, retries
+```
+
+Query fingerprints are stable across bound values and never contain the values
+themselves. See [Observability](docs/OBSERVABILITY.md).
+
+## CLI example
+
+The package installs an `aura` console script for offline, server-independent tasks:
+
+```bash
+aura version
+aura doctor                                            # environment, deps, native status
+aura schema compile --app myapp.models --out schema.json
+aura migrate diff --from old.json --to myapp.models --require-safe
+aura explain file query-ir.json                        # client-side static plan
+aura bench local --iterations 20000                    # in-process micro-benchmarks
+aura generate stubs --models myapp/models.py           # faithful .pyi from models
+```
+
+See [CLI](docs/CLI.md).
+
+## Native acceleration
+
+The pure-Python core is the complete, benchmarked baseline and is always available. An
+optional in-repository Rust/PyO3 extension accelerates two byte-exact hot paths (frame
+CRC32 and fixed-dimension f32 vector packing) when built and installed. The public API and
+all observable behaviour are identical with or without it, parity is enforced by tests,
+and `AURA_DISABLE_NATIVE=1` forces the pure-Python path.
+
+No zero-copy behaviour is claimed, and the native path is not always faster: in the
+included benchmark, CRC32 through the native path can be slower than Python's optimized
+zlib routine on some inputs, while vector packing is faster. Measure on your own hardware.
+See [Native acceleration](docs/NATIVE_ACCELERATION.md).
+
+## AuraDB boundary
+
+This package is the client and connector. AuraDB server features are a separate future
+project. Operations that require a live cluster (applying migrations, server-side cost
+estimation, distributed transaction coordination) fail with a structured error rather than
+pretending to succeed. See [AuraDB boundary](docs/AURADB_BOUNDARY.md).
+
+## Documentation
+
+- [Getting Started](docs/GETTING_STARTED.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Models](docs/MODELS.md) and [Vectors](docs/VECTORS.md)
+- [Query Builder](docs/QUERY_BUILDER.md)
+- [Client](docs/CLIENT.md)
+- [Protocol](docs/PROTOCOL.md) and [Transports](docs/TRANSPORTS.md)
+- [Observability](docs/OBSERVABILITY.md) and [Migrations](docs/MIGRATIONS.md)
+- [Errors](docs/ERRORS.md) and [Testing](docs/TESTING.md)
+- [Native Acceleration](docs/NATIVE_ACCELERATION.md) and [AuraDB Boundary](docs/AURADB_BOUNDARY.md)
+
+## Benchmarks
+
+The `benchmarks/` directory contains real, in-process micro-benchmarks for protocol
+encode/decode, model hydration, Query IR construction, vector serialization, an
+end-to-end round trip through the reference transport, and pure-Python versus native
+acceleration. They print measured timings on your machine:
+
+```bash
+python benchmarks/bench_protocol.py
+python benchmarks/bench_native_acceleration.py
+```
+
+Numbers vary by hardware. The benchmarks contain no precomputed or fabricated results.
+
+## Testing
+
+```bash
+python -m pytest -vv
+```
+
+The suite is deterministic and requires no external services. It covers models, fields,
+vectors, schema generation, the query builder, protocol frames and golden bytes,
+transports, client lifecycle, hydration, errors, migrations, observability, typing, and
+example smoke tests. See [Testing](docs/TESTING.md).
+
+## Security
+
+The client validates and length-bounds every protocol frame, fails closed on protocol
+errors, never embeds secrets in errors or logs, and redacts credentials in configuration
+`repr`. To report a vulnerability, see [SECURITY.md](SECURITY.md).
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, the dev and
+native build, test commands, and code style. Please also read our
+[Code of Conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).