provisa 0.1.0a244__tar.gz

provisa-0.1.0a244/LICENSE

@@ -0,0 +1,89 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Kenneth Stott
+Licensed Work:        Provisa (this repository and any accompanying code, data,
+                      or assets). The Licensed Work is (c) 2026 Kenneth Stott.
+Additional Use Grant: In addition to non-production use, production use by
+                      individuals and organizations with fewer than 100 total
+                      employees and contractors and with less than 1,000,000 USD
+                      (or equivalent) total revenue in the prior tax year is
+                      permitted. Any production use by larger organizations
+                      requires a separate commercial license.
+Change Date:          The fourth anniversary of the date on which each released
+                      version of the Licensed Work is first made publicly
+                      available by the Licensor.
+Change License:       GNU General Public License, Version 2.0 or later.
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact: kennethstott@gmail.com
+
+Notice
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production
+use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under the
+terms of the Change License, and the rights granted in the paragraph above
+terminate.
+
+If your use of the Licensed Work does not comply with the requirements currently
+in effect as described in this License, you must purchase a commercial license
+from the Licensor, its affiliated entities, or authorized resellers, or you must
+refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works of
+the Licensed Work, are subject to this License. This License applies separately
+for each version of the Licensed Work and the Change Date may vary for each
+version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy of
+the Licensed Work. If you receive the Licensed Work in original or modified form
+from a third party, the terms and conditions set forth in this License apply to
+your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other versions
+of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of Licensor
+or its affiliates (provided that you may use a trademark or logo of Licensor as
+expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN
+"AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS
+OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license your
+works, and to refer to it using the trademark "Business Source License", as long
+as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business Source
+License" name and trademark, Licensor covenants to MariaDB, and to all other
+recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version, or
+   a license that is compatible with GPL Version 2.0 or a later version, where
+   "compatible" means that software provided under the Change License can be
+   included in a program with software provided under GPL Version 2.0 or a later
+   version. Licensor may specify additional Change Licenses without limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as the
+   Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

provisa-0.1.0a244/NOTICE

@@ -0,0 +1,26 @@
+Provisa
+Copyright (c) 2026 Kenneth Stott
+
+This product is licensed under the Business Source License 1.1 (see LICENSE).
+
+AI / Machine-Learning Training Notice
+-------------------------------------
+The Licensor does not consent to the use of the Licensed Work, or any portion
+of it, or any outputs derived from it, for training, fine-tuning, instructing,
+or otherwise developing or improving (directly or indirectly) any machine
+learning, foundation, or generative AI model, or for creating datasets for such
+purposes ("AI Training Use").
+
+This is a reservation of rights and a declared opt-out under applicable text-
+and data-mining and copyright frameworks. It is a notice of the Licensor's
+intent, not an additional restriction on the rights granted by the Business
+Source License 1.1. Any party wishing to make AI Training Use of the Licensed
+Work must obtain a separate written license from the Licensor:
+kennethstott@gmail.com
+
+Machine-readable opt-out signals accompanying this repository:
+  - robots.txt  (crawler exclusion for known AI/data-collection agents)
+  - ai.txt      (Do-Not-Train declaration)
+
+Attribution notices in the Licensed Work must be preserved in copies and
+derivative works, as required by the Business Source License 1.1.

provisa-0.1.0a244/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: provisa
+Version: 0.1.0a244
+Summary: Config-driven data virtualization platform
+Requires-Python: <3.13,>=3.12
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: fastapi
+Requires-Dist: uvicorn
+Requires-Dist: asyncpg
+Requires-Dist: pydantic>=2
+Requires-Dist: strawberry-graphql[fastapi]
+Requires-Dist: pyyaml
+Requires-Dist: graphql-core>=3.2
+Requires-Dist: sqlglot
+Requires-Dist: trino
+Requires-Dist: grpcio
+Requires-Dist: grpcio-tools
+Requires-Dist: grpcio-reflection
+Requires-Dist: pyarrow
+Requires-Dist: adbc-driver-flightsql
+Requires-Dist: adbc-driver-manager
+Requires-Dist: httpx
+Requires-Dist: redis[hiredis]
+Requires-Dist: fakeredis
+Requires-Dist: anthropic
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: aisuite>=0.1
+Requires-Dist: apscheduler>=3.10
+Requires-Dist: inflect
+Requires-Dist: jsonpath-ng
+Requires-Dist: PyJWT[crypto]
+Requires-Dist: bcrypt
+Requires-Dist: motor
+Requires-Dist: elasticsearch<9,>=8
+Requires-Dist: aiokafka
+Requires-Dist: websockets>=11.0
+Requires-Dist: boto3
+Requires-Dist: cryptography
+Requires-Dist: sqlalchemy>=2
+Requires-Dist: duckdb-engine
+Requires-Dist: clickhouse-connect
+Requires-Dist: clickhouse-driver
+Requires-Dist: chdb; sys_platform != "win32"
+Requires-Dist: snowflake-connector-python[pandas]
+Requires-Dist: databricks-sql-connector
+Requires-Dist: google-cloud-bigquery
+Requires-Dist: google-cloud-bigquery-storage
+Requires-Dist: google-cloud-storage
+Requires-Dist: protobuf<7,>=6.33.5
+Requires-Dist: grpcio-status<1.82
+Requires-Dist: pyodbc
+Requires-Dist: azure-identity
+Requires-Dist: psycopg2-binary
+Requires-Dist: opentelemetry-sdk
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc
+Requires-Dist: opentelemetry-exporter-otlp-proto-http
+Requires-Dist: opentelemetry-instrumentation-fastapi
+Requires-Dist: opentelemetry-instrumentation-httpx
+Requires-Dist: opentelemetry-instrumentation-asyncpg
+Requires-Dist: opentelemetry-instrumentation-redis
+Requires-Dist: opentelemetry-instrumentation-pymongo
+Requires-Dist: opentelemetry-instrumentation-elasticsearch
+Requires-Dist: opentelemetry-instrumentation-grpc
+Requires-Dist: python-dateutil
+Requires-Dist: duckdb
+Requires-Dist: networkx>=3.0
+Requires-Dist: scipy
+Requires-Dist: defusedxml
+Requires-Dist: jpype1
+Requires-Dist: minio
+Requires-Dist: pyiceberg
+Requires-Dist: neo4j
+Requires-Dist: aiosqlite
+Requires-Dist: greenlet
+Provides-Extra: embedded
+Requires-Dist: duckdb; extra == "embedded"
+Requires-Dist: aiosqlite; extra == "embedded"
+Requires-Dist: greenlet; extra == "embedded"
+Requires-Dist: fakeredis; extra == "embedded"
+Provides-Extra: telemetry-pg
+Requires-Dist: pgserver; extra == "telemetry-pg"
+Provides-Extra: desktop
+Requires-Dist: mcp-proxy; extra == "desktop"
+Provides-Extra: mysql
+Requires-Dist: aiomysql; extra == "mysql"
+Provides-Extra: sqlserver
+Requires-Dist: aioodbc; extra == "sqlserver"
+Provides-Extra: oracle
+Requires-Dist: oracledb; extra == "oracle"
+Provides-Extra: all-drivers
+Requires-Dist: aiomysql; extra == "all-drivers"
+Requires-Dist: aioodbc; extra == "all-drivers"
+Requires-Dist: oracledb; extra == "all-drivers"
+Provides-Extra: govdata
+Requires-Dist: askamerica[engine]; extra == "govdata"
+Provides-Extra: firebase
+Requires-Dist: firebase-admin; extra == "firebase"
+Provides-Extra: vault
+Requires-Dist: hvac; extra == "vault"
+Provides-Extra: azure
+Requires-Dist: azure-keyvault-keys; extra == "azure"
+Provides-Extra: gcp
+Requires-Dist: google-cloud-kms; extra == "gcp"
+Provides-Extra: kms-all
+Requires-Dist: hvac; extra == "kms-all"
+Requires-Dist: azure-keyvault-keys; extra == "kms-all"
+Requires-Dist: google-cloud-kms; extra == "kms-all"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-bdd; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: pyright; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: bandit; extra == "dev"
+Requires-Dist: pip-audit; extra == "dev"
+Requires-Dist: import-linter; extra == "dev"
+Requires-Dist: syrupy; extra == "dev"
+Requires-Dist: respx; extra == "dev"
+Requires-Dist: python-pptx; extra == "dev"
+Requires-Dist: aiosqlite; extra == "dev"
+Requires-Dist: greenlet; extra == "dev"
+Requires-Dist: pandas; extra == "dev"
+Requires-Dist: aiomysql; extra == "dev"
+Requires-Dist: oracledb; extra == "dev"
+Dynamic: license-file

provisa-0.1.0a244/README.md

@@ -0,0 +1,364 @@
+# Provisa
+
+I almost called this project *Insanity*. The surface area looked impossible — 46 kinds of data source on one side, a Babel of query languages and wire protocols on the other. Chasing all of it seemed insane.
+
+Then the core fell out: one federation model, one intermediate representation, a thin contract for sources and another for consumers. Once those held, the surface area became tractable — and the real insanity came into focus. It isn't building this. It's trying to govern data from *outside* the data environment: a catalog here, a policy engine there, a lineage graph somewhere else, each a copy of the truth that drifts on freshness, misses on coverage, and describes access instead of enforcing it. The only sane move is to put governance on the path every query already takes.
+
+That's Provisa. A single governed API over 46 heterogeneous data sources — query it with **GraphQL, Cypher, or SQL**, consume it over **pgwire, Bolt, gRPC, REST, Arrow Flight, or JDBC**. RLS, column masking, and query approval aren't a layer bolted on top; they *are* the path. No query reaches data without passing through governance, so coverage is total by construction, not by diligence.
+
+Put another way, this is what a semantic layer was supposed to be. Every prior one — dbt, Cube, LookML — is *passive*: a metadata description of your data that some other engine may or may not consult. Provisa is an **active semantic layer** — the model isn't documentation the engine reads, it *is* the engine. Registered domains and relationships are the only legal join paths; governance is compiled into the plan; every request is enforced inline because no execution path goes around it. And because the same governed path serves SQL, GraphQL, and Cypher over pgwire, Bolt, Flight, JDBC, and REST, effectively all of your cross-system data movement — system-to-system, analytical, application, and human — travels through one place that both describes the data and enforces the rules on it. Describing your data and governing it become the same act.
+
+GraphQL, Cypher, and SQL are all first-class over federated data — something no federated engine offers natively. And that's not three integrations but one. Every query language lowers to a single intermediate representation, and governance is injected there — one place, so it cannot drift between languages, and the same IR retargets to any source dialect on the way out. A new query language is a front-end onto that shared governed core, not a new engine, which is why the IR can absorb almost any query dialect. If that sounds too good to be true: some languages carry a small compromise at the edges, but every core language feature is supported — you are not writing a crippled subset. And it isn't read-only: most federation engines are. Provisa carries both analytical and transactional flows through the same governed API. Cross-source reads fan out through the federation layer; writes and single-source reads route direct to the source driver — governed the same way, but transactional and sub-100ms. Arrow Flight columnar streaming is built in, not bolted on. Distributed traces, metrics, and logs are automatically registered as queryable tables in the same schema as your business data, so observability is just another join.
+
+## Features
+
+### Query Interfaces
+
+These are the languages and structured APIs you write queries in. Each has its own syntax and semantics; governance (RLS, masking, column visibility, relationship enforcement) applies uniformly across all of them regardless of which wire protocol delivers them.
+
+- **GraphQL** — Per-role schemas with field-level visibility, filtering, cursor-based pagination, and aggregate queries (`count`, `sum`, `avg`, `min`, `max`). Schema-constrained to registered relationships — structurally valid by construction, the fastest path to a correct simple query. Apollo APQ included: queries are hashed and registered server-side; subsequent calls send only the hash over HTTP GET, making responses CDN-cacheable with zero client changes required. Lookup tables below a configurable row threshold are exposed as enum types.
+- **SQL** — Full SQL over federated data; unconstrained and more expressive than GraphQL. Write standard SQL — correlated subqueries and all — and it runs across sources unchanged. Single-source queries bypass the federation layer entirely (sub-100ms).
+- **Cypher** — Graph query language over the same federated schema. Traverse relationships as graph edges; union sources; variable-length paths. Governance applies identically to GraphQL and SQL.
+- **gRPC model API** — Auto-generated `.proto` from the registered schema; typed query and insert RPCs per table, streamed responses. Schema-driven in the same sense as GraphQL — the registration model is the contract, protobuf is the wire encoding. Unlike Arrow Flight (which is a columnar streaming transport), this is a full per-table query interface.
+- **JSON:API** — Structured query API at `/data/jsonapi/{table}`, HTTP-only by design. Supports JSON:API 1.1: sparse fieldsets (`fields[table]=col1,col2`), filter expressions (`filter[field][op]=value`), compound documents (`include=relation`), and sort. Not a general-purpose query language — queries one table at a time with standardized filter syntax rather than an ad-hoc query string.
+- **Query Language Explorer** — Write a GraphQL query and see live **Semantic SQL** and **Cypher** translations in side panels; copy either or jump directly into the SQL or Graph editor. A practical workflow is to sketch query fragments in GraphQL, then stitch the resulting SQL into complex views or reports.
+
+The Explorer shows a GraphQL query alongside its live SQL and Cypher translations:
+
+![Query Language Explorer](docs/images/query-explorer.png)
+
+The same federated schema is explorable as a live graph — domain and node labels, relationship types, and variable-length traversals:
+
+![Graph Visualization](docs/images/graph-view.png)
+
+### Query Composition Tools
+
+These tools help you write queries in the above languages — they are not query languages themselves.
+
+- **Natural language query** — NL→SQL/Cypher/GraphQL pipeline powered by Claude. Describe what you want in plain English; the pipeline produces a query in your chosen language with an interactive validation loop before execution.
+
+![Natural Language Query](docs/images/natural-language.png)
+
+### Wire Protocols
+
+These are the connection protocols. SQL, GraphQL, and Cypher ride over them — the choice of wire protocol does not change the query interface or governance behaviour.
+
+- **pgwire** — Any PostgreSQL client (psql, DBeaver, DataGrip, asyncpg, SQLAlchemy, pandas `read_sql`) connects on port 5439 as if it were a Postgres server. Accepts SQL only. Full governance pipeline applies. `pg_catalog` and `information_schema` answered from an in-memory catalog so schema browsers work without a federation round-trip. TLS optional.
+- **Bolt (Neo4j)** — Any Neo4j client (Neo4j Browser, Bloom, official drivers) connects over the Bolt protocol and runs Cypher against the federated graph. Each role the user holds surfaces as a `provisa_<role>` database. Same governance as every other transport. TLS optional.
+- **Arrow Flight** — High-throughput columnar streaming over gRPC; accepts GraphQL or SQL as the query input. Unbounded result sets, no server-side materialization, no separate infrastructure required.
+- **JDBC** — BI tool integration (Tableau, Power BI, DBeaver) in `approved` or `catalog` mode.
+- **WebSocket / SSE** — Subscriptions: near-real-time change events; backends: PG native, MongoDB native, CDC, polling. Also exposed over Kafka.
+
+### Data Sources
+
+- **46 source types** — PostgreSQL, MySQL, MongoDB, Cassandra, Elasticsearch, Neo4j, SPARQL triplestores, Kafka, Google Sheets, and more through a single API; graph and RDF sources are first-class, not adapters
+- **Smart routing** — Single-source queries bypass federation (sub-100ms); multi-source queries route through the federation layer — bring your own cluster or use the embedded workers
+- **API sources** — Register REST, GraphQL, gRPC, WebSocket, or RSS endpoints as queryable tables; SPARQL helpers included; federated joins across API sources and relational sources work transparently
+- **Remote schema introspection** — Point at any GraphQL, OpenAPI, or gRPC endpoint; documented operations are automatically surfaced as queryable tables, graph nodes, and edges with full governance applied on top
+- **File sources** — CSV, Parquet, and SQLite files as queryable tables; supports local paths and remote object storage (`s3://`, `ftp://`, `sftp://`)
+- **Kafka integration** — Topics as read-only tables; query results as Kafka sinks
+- **Scheduled triggers** — Cron and interval triggers (APScheduler) that fire webhooks, mutations, or Kafka sink publishes
+- **Federation performance hints** — SQL-comment routing hints override automatic routing decisions
+
+![Data Sources](docs/images/data-sources.png)
+
+Sources, files, and remote endpoints are registered as governed tables from the UI:
+
+![Table Registration](docs/images/table-registration.png)
+
+### Security & Governance
+
+- **Row-level security** — Per-table, per-role WHERE clause injection
+- **Column masking** — Per-column masking (regex, constant, truncate) with role-based bypass
+- **Column presets** — Server-side static or session-variable values injected on insert/update; not exposed in mutation input types
+- **Write permissions** — Per-column mutation access control (`writable_by`)
+- **Inherited roles** — Roles inherit RLS, visibility, and masking from a parent role recursively
+- **Tracked functions & webhooks** — DB functions and outbound webhooks exposed as GraphQL mutations with typed return shapes
+- **ABAC approval hook** — Pre-execution authorization hook; webhook, gRPC, or unix_socket transport; per-table, per-source, or global scope; configurable fallback policy
+- **Pluggable auth** — Firebase, Keycloak, OAuth 2.0, simple (testing)
+
+![Security Roles](docs/images/security-roles.png)
+
+### Delivery & Performance
+
+- **Materialized views as recorded transforms** — An MV captures the transform that produced it: its join shape or SQL, the per-source input signals (Iceberg snapshot, RDB watermark) it was built from, and a determinism check at registration. Because the transform is recorded, queries (or subexpressions) are transparently rewritten onto a fresh MV — structural join-pattern matching with partial-match support, so an MV covering a subset of joins still applies, with remaining joins preserved
+- **Hot table inlining** — Small frequently-joined lookup tables are inlined as VALUES CTEs directly in the query plan, eliminating cross-source round trips for dimension data
+- **Query caching** — Role+RLS-partitioned Redis result cache; APQ hash cache included
+- **Observability as data** — Distributed traces, metrics, and logs are collected via OpenTelemetry, compacted into Iceberg on S3, and automatically registered as queryable tables (`traces`, `metrics`, `logs`, `queries`) in the federated schema; query them with SQL, GraphQL, or Cypher alongside your business data — join a `customers` table to the `queries` table to see who ran what and how long it took
+
+### Administration & Integration
+
+- **Admin API** — GraphQL at `/admin/graphql`; config upload/download, relationship editing, query approval
+- **GraphQL Voyager** — Interactive role-scoped schema visualization as an entity-relationship diagram
+- **LLM relationship discovery** — Claude-powered foreign key candidate suggestions
+- **Python client** — `pip install provisa-client`; GraphQL/SQL → DataFrames, Arrow Flight → pyarrow Tables, SQLAlchemy dialect, ADBC support
+- **Data ingestion** — HTTP endpoints for pushing JSON event data into the platform
+- **Hasura v2 / DDN import** — Convert Hasura v2 metadata or DDN supergraph YAML to Provisa config
+- **Apollo Federation** — Expose Provisa as an Apollo Federation v2 subgraph
+
+Role-scoped schema visualized as an entity-relationship diagram (GraphQL Voyager):
+
+![Schema Voyager](docs/images/schema-voyager.png)
+
+Relationships are registered, approved, and enforced as the only legal JOIN paths:
+
+![Relationships](docs/images/relationships.png)
+
+## Security Model
+
+This is where "on the path every query already takes" stops being a slogan. Provisa enforces a multi-layered security model across every query language (GraphQL, SQL, Cypher) and every transport (REST, gRPC, Arrow Flight, JDBC, pgwire, Bolt, WebSocket). Governance is applied uniformly — there is no query path that bypasses it. Coverage is total by construction, not by diligence: add a source, column, or relationship and every layer applies to it automatically, with nothing to remember to register.
+
+The layers apply in order. A request must clear each layer before the next is evaluated.
+
+### Layer 0 — Introspection filtering
+
+The schema and catalog presented to a role contain only the tables in its `domain_access` list and the columns that pass per-column `visible_to` rules. Objects outside a role's access are invisible at discovery time — they cannot be queried, autocompleted, or inferred to exist. This applies to the GraphQL schema, SQL catalog, and the query editor's schema browser.
+
+### Layer 1 — Public access
+
+Tables in domains with no `domain_access` restriction are visible to all authenticated identities with no additional configuration. Zero friction for genuinely public data.
+
+### Layer 2 — Domain access
+
+Each role carries a `domain_access` list of domain IDs. A query that touches a table outside those domains is rejected before execution. This is the coarse ownership boundary — an HR role cannot reach finance tables regardless of how the SQL is written.
+
+### Layer 3 — Row-level security
+
+After domain access is confirmed, per-table, per-role `WHERE` predicates are injected into every `SELECT` at execution time. The predicates evaluate against raw data. A regional manager querying a shared orders table sees only their region's rows even on a `SELECT *`.
+
+### Layer 4 — Column visibility and masking
+
+Columns with a `visible_to` list that excludes the requesting role are stripped from query output. Columns with a masking rule have their values replaced — regex redaction, constant replacement, or truncation — before results leave the server. Masking applies in all query languages and output formats.
+
+### Layer 5 — Predicate guard
+
+Masked columns are rejected from `WHERE` and `HAVING` clauses. Without this, a caller could infer the unmasked value by binary-searching it in a filter even though the output is masked. Rejection is enforced at query parse time, before execution.
+
+### Relationship governance
+
+JOIN conditions in SQL must match a registered, approved relationship between tables. Unapproved joins are rejected. Each relationship carries a human-readable reason and description — guidance for both users and autonomous agents about why a traversal path exists. This is governance policy, not a hard security boundary: Layers 2–5 hold regardless of join structure, so a deliberate circumvention does not expose data the role could not reach through two separate queries. Circumvention attempts are logged and auditable.
+
+---
+
+These layers compose. A role with domain access, RLS, and masked columns has all five constraints active simultaneously. Adding a new data source, column, or relationship does not require updating every rule — each layer is configured independently and applies automatically to any query that touches governed objects.
+
+### macOS
+1. Download the DMG from the [releases page](https://github.com/kenstott/provisa/releases/latest)
+2. Drag **Provisa.app** to `/Applications` and double-click to launch
+3. First launch completes a one-time setup (~2 min, no internet required)
+4. Open Terminal:
+```bash
+provisa start   # start all services
+provisa open    # open the UI in your browser
+```
+
+### Linux
+1. Download `Provisa-<version>-linux-x86_64.AppImage` from the [releases page](https://github.com/kenstott/provisa/releases/latest)
+2. Make it executable and run it — first launch completes a one-time setup (no internet required):
+```bash
+chmod +x Provisa-*-linux-x86_64.AppImage
+./Provisa-*-linux-x86_64.AppImage
+provisa start && provisa open
+```
+
+### Windows
+1. Download `Provisa-<version>-windows-x64.exe` from the [releases page](https://github.com/kenstott/provisa/releases/latest)
+2. Run the installer — no admin rights required
+3. Open **Provisa First Launch** from the Start Menu — completes a one-time setup (~5 min, no internet required)
+4. Open a new terminal:
+```
+provisa start
+```
+
+### First Query
+
+In local development (`PROVISA_MODE=test`), no credentials are required. In production, authenticate with a Bearer token — the role is extracted from it automatically.
+
+```bash
+# Local dev — no auth required, role defaults to admin
+curl -X POST http://localhost:8001/data/graphql \
+  -H "Content-Type: application/json" \
+  -d '{"query": "{ orders { id amount region } }"}'
+
+# Ad-hoc SQL works the same way
+curl -X POST http://localhost:8001/data/graphql \
+  -H "Content-Type: application/json" \
+  -d '{"query": "SELECT id, amount, region FROM orders"}'
+
+# Production — authenticate with a Bearer token; role is derived from the token
+curl -X POST https://provisa.example.com/data/graphql \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"query": "{ orders { id amount region } }"}'
+```
+
+### JDBC (Tableau, DBeaver, Power BI)
+
+Download `provisa-jdbc-<version>.jar` from the [releases page](https://github.com/kenstott/provisa/releases/latest) and add it to your BI tool's driver path.
+
+```
+jdbc:provisa://localhost:8815
+```
+
+Authenticate with your Provisa username and password — the server assigns your role.
+
+- **`catalog` mode** — full schema visible; use with catalog tools (Collibra, Atlan, DBeaver)
+
+See [docs/integrations.md](docs/integrations.md) for Tableau and Power BI setup steps.
+
+### PostgreSQL Wire Protocol (pgwire)
+
+Provisa speaks the PostgreSQL wire protocol on port 5439. Any client that can connect to Postgres connects to Provisa — no driver, no adapter, no changes to existing tooling.
+
+**The PostgreSQL username selects the Provisa role.** With `provider: none` (trust mode), the password is ignored and any configured role name is accepted as the username — connect as `analyst`, `admin`, or any role to see that role's governed view of the data. With `provider: simple`, the password is bcrypt-validated. Other providers (`firebase`, `keycloak`, `oauth`) are not supported over pgwire.
+
+```bash
+# psql — connect as analyst role
+psql -h localhost -p 5439 -U analyst
+
+# psql — connect as admin role
+psql -h localhost -p 5439 -U admin
+
+# asyncpg (Python) — role = username, password ignored in trust mode
+conn = await asyncpg.connect(host="localhost", port=5439, user="analyst", password="x")
+rows = await conn.fetch("SELECT id, amount FROM orders WHERE region = 'west'")
+
+# SQLAlchemy
+engine = create_engine("postgresql+psycopg2://analyst:x@localhost:5439/provisa")
+
+# pandas
+df = pd.read_sql("SELECT * FROM orders", engine)
+```
+
+All queries run through the full governance pipeline — domain access, RLS, masking, and predicate guard apply exactly as they do for GraphQL and REST. Schema browsers (DBeaver, DataGrip, pgAdmin) work out of the box: `pg_catalog` and `information_schema` queries are answered from an in-memory catalog scoped to the role's domain access, so users see only the tables and columns they are permitted to query.
+
+DataGrip browsing the governed schema and its foreign-key diagram over pgwire — no driver, no adapter:
+
+![Provisa in DataGrip over pgwire](docs/images/pgwire-datagrip.png)
+
+TLS is enabled by setting `PROVISA_PGWIRE_CERT` and `PROVISA_PGWIRE_KEY`. The port is configurable via `PROVISA_PGWIRE_PORT` (default `5439`).
+
+### Bolt (Neo4j Wire Protocol)
+
+Provisa also speaks the Neo4j **Bolt** protocol, so graph-native tools connect directly and run Cypher against the federated graph — no export, no separate graph database. Point **Neo4j Browser** or **Bloom** at Provisa and traverse relationships across sources with the same governance (domain access, RLS, masking) applied.
+
+Neo4j Browser running Cypher against Provisa — node labels, relationship types, and property keys come straight from the registered schema:
+
+![Provisa in Neo4j Browser over Bolt](docs/images/bolt-neo4j-browser.png)
+
+Enable it by setting `PROVISA_BOLT_PORT` (Neo4j's default is `7687`). TLS is enabled with `PROVISA_BOLT_CERT` and `PROVISA_BOLT_KEY`. Each Provisa role the authenticated user holds surfaces as a selectable `provisa_<role>` database (the `provisa_admin` selector above) — choosing one narrows the session to that role's domain rights; the user can never exceed the roles they hold.
+
+### Python Client
+
+```bash
+pip install provisa-client                       # core
+pip install "provisa-client[pandas]"             # + DataFrame support
+pip install "provisa-client[sqlalchemy]"         # + SQLAlchemy dialect
+pip install "provisa-client[adbc]"               # + ADBC over Arrow Flight
+```
+
+```python
+from provisa_client import ProvisaClient, connect
+
+# GraphQL → DataFrame
+client = ProvisaClient("http://localhost:8001", username="alice", password="secret")
+df = client.query_df("{ orders { id amount region } }")
+
+# SQL → DataFrame
+df = client.query_df("SELECT id, amount, region FROM orders WHERE region = 'west'")
+
+# Arrow Flight → pyarrow Table (high-throughput columnar)
+table = client.flight("{ orders { id amount region } }")
+
+# DB-API 2.0 (PEP 249) — GraphQL or SQL, detected automatically
+with connect("http://localhost:8001", username="alice", password="secret") as conn:
+    cur = conn.cursor()
+
+    # GraphQL
+    cur.execute("{ orders { id amount region } }")
+    rows = cur.fetchall()
+
+    # SQL (routed through governance engine — RLS and masking applied)
+    cur.execute("SELECT id, amount FROM orders WHERE region = %s", ("west",))
+    rows = cur.fetchall()
+
+# SQLAlchemy dialect — provisa+http:// or provisa+https://
+from sqlalchemy import create_engine, text
+import pandas as pd
+
+engine = create_engine("provisa+http://alice:secret@localhost:8001")
+
+# pandas read_sql — GraphQL or SQL
+df = pd.read_sql("{ orders { id amount region } }", engine)
+df = pd.read_sql("SELECT id, amount, region FROM orders WHERE region = 'west'", engine)
+
+# raw execute
+with engine.connect() as conn:
+    rows = conn.execute(text("SELECT id, amount FROM orders")).fetchall()
+
+# role + mode URL parameters (mode=catalog for arbitrary SQL)
+engine = create_engine(
+    "provisa+http://alice:secret@localhost:8001?role=analyst&mode=catalog"
+)
+
+# ADBC — Arrow-native streaming via Flight
+from provisa_client.adbc import adbc_connect
+with adbc_connect("http://localhost:8001", user="alice", password="secret") as conn:
+    with conn.cursor() as cur:
+        cur.execute("{ orders { id amount } }")
+        table = cur.fetch_arrow_table()
+```
+
+See [docs/python-client.md](docs/python-client.md) for full reference.
+
+## Documentation
+
+| Topic | Doc |
+|-------|-----|
+| Developer quick start (running from source) | [docs/quickstart.md](docs/quickstart.md) |
+| Full YAML configuration reference | [docs/configuration.md](docs/configuration.md) |
+| Endpoint reference (GraphQL, REST, Flight, gRPC) | [docs/api-reference.md](docs/api-reference.md) |
+| System design and component map | [docs/architecture.md](docs/architecture.md) |
+| Security model (RLS, masking, auth) | [docs/security.md](docs/security.md) |
+| Supported source types | [docs/sources.md](docs/sources.md) |
+| SSE subscriptions | [docs/subscriptions.md](docs/subscriptions.md) |
+| JDBC, BI tools, Arrow Flight clients, Apollo Federation | [docs/integrations.md](docs/integrations.md) |
+| Python client (`provisa-client`) | [docs/python-client.md](docs/python-client.md) |
+| Admin API | [docs/admin.md](docs/admin.md) |
+| Deployment (Docker Compose, Kubernetes, macOS) | [docs/deployment.md](docs/deployment.md) |
+| Hasura v2 / DDN import | [docs/import.md](docs/import.md) |
+| Release workflow (alpha/beta/stable tags) | [docs/releasing.md](docs/releasing.md) |
+
+## Sizing
+
+Provisa includes a built-in federation engine for multi-source queries. At first launch you choose a RAM budget; Provisa derives the number of local federation workers automatically.
+
+| Host RAM | Workers | Typical workload |
+|----------|---------|-----------------|
+| < 24 GB  | 0       | Development, single-source queries, small teams |
+| 24–47 GB | 1       | Small team, moderate cross-source queries |
+| 48–95 GB | 2       | Departmental deployment, mixed BI + notebook usage |
+| 96 GB+   | 4       | Large department, heavy concurrent federation |
+
+Worker count can be changed at any time by editing `~/.provisa/config.yaml` (`federation_workers: N`) and running `provisa restart`. Set to `0` to run coordination-only (single-node).
+
+### Scaling beyond a single box
+
+**Horizontal scale-out** — Run multiple Provisa instances behind a load balancer. Each instance is a fully functioning system. All instances must point at the same config DB (set `CONFIG_DB_HOST` on secondary boxes) and optionally a shared Redis instance (`REDIS_URL`) for a unified cache. Most queries distribute transparently; very large cross-source joins may exceed the resources of a single instance and require a larger box or an external federation cluster.
+
+**Shared Redis** — Set `REDIS_URL` on each instance to point at an external Redis. Shared Redis means cache entries from one instance are available to all, improving hit rates across the cluster.
+
+**Bring your own federation cluster** — Point Provisa at an existing external federation cluster instead of the embedded workers. Recommended for large-scale or cloud deployments; see [docs/deployment.md](docs/deployment.md) for configuration.
+
+## License
+
+Business Source License 1.1 (unmodified, per MariaDB's Licensor covenants). Each
+released version converts to the Change License (GPL v2.0 or later) on the 4th
+anniversary of its public release; current and recent code stays under BSL.
+Production use above the Additional Use Grant thresholds (fewer than 100
+employees/contractors and under $1M prior-year revenue) requires a commercial
+license. See [LICENSE](LICENSE).
+
+The Licensor does not consent to use of this work for AI/ML training. See
+[NOTICE](NOTICE), [ai.txt](ai.txt), and [robots.txt](robots.txt). For commercial
+or AI-training licenses: kennethstott@gmail.com

provisa-0.1.0a244/provisa/__init__.py

@@ -0,0 +1,9 @@
+# Copyright (c) 2026 Kenneth Stott
+# Canary: 10926cca-c492-48cf-889a-d55181674ef3
+#
+# This source code is licensed under the Business Source License 1.1
+# found in the LICENSE file in the root directory of this source tree.
+#
+# NOTICE: Use of this software for training artificial intelligence or
+# machine learning models is strictly prohibited without explicit written
+# permission from the copyright holder.