sourcesql 0.1.0__tar.gz

sourcesql-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.agents/
+skills-lock.json
+.DS_Store
+local/
+artifacts/
+dist/
+.env*
+!.env.example
+.dev.vars*
+!.dev.vars.example
+spikes/*/node_modules/
+spikes/*/.wrangler/
+spikes/*/dist/
+spikes/*/generated/
+spikes/*/.vercel/
+apps/research/node_modules
+apps/research/dist/
+apps/research/.ui-builds/
+apps/research/.data/
+apps/research/.tunnel/
+apps/research/.vercel/
+apps/research/.vercel-assets/

sourcesql-0.1.0/AGENTS.md

@@ -0,0 +1,13 @@
+# sourcesQL implementation
+
+The owner authorized local implementation on 2026-10-13, including subagents. Build a working independent engine and integrate an isolated copy of the existing Results Demo. Preserve the original app and memoriesQL checkouts.
+
+Fixture mode is the default. Live provider calls require explicit configured credentials, destination permissions and an owner-approved total budget. No publication, upstream modification or external messages are implied. Keep private handoff documents, operator state and credentials outside public artifacts.
+
+The host authors research SQL; the engine owns AST admission, typed staged evaluation, finite execution and immutable results. Use SQLGlot 30.19.0; never prefix/regex-only admission. No network UDFs in DuckDB, arbitrary file readers or query-owned policy. Unknown and failed are distinct; exact quotes establish textual support rather than truth. Corrections append revisions in the app store. Exports and result reuse reauthorize complete dependencies.
+
+Delegate only nonoverlapping file lanes; root owns shared contracts, storage/worker/coordinator, integration and release evidence. Advertise only tested implemented behavior. Full live/host qualification is separate from fixture tests. Surface consequential product decisions, continue independent work, and keep STATUS.md accurate.
+
+Public product naming is sourcesQL. Keep competitor research, comparison plans, benchmark evidence and results in ignored local files; do not commit or publish them. Preserve SQL syntax and ordinary UI selection terminology when cleaning up product names.
+
+When asked to cut a PR, create it open and ready for review, subscribe to comments, and fix/respond to Codex Code Review comments.

sourcesql-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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.

sourcesql-0.1.0/NOTICE

@@ -0,0 +1,10 @@
+sourcesQL
+Copyright 2026 John Inniger
+
+SQL admission, immutable result, accounting and evidence invariants are informed
+by selected public memoriesQL contracts and tests, Apache-2.0, at commit
+539fde637249fec68629ab25cbab5ffc95d5d055. Specific reuse is recorded in provenance/.
+
+SQLGlot is a separately installed MIT dependency; its source is not bundled.
+The research app derives from the owner's existing Results Demo source; its
+origin and modifications are recorded in provenance/app-reuse.json.

sourcesql-0.1.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: sourcesql
+Version: 0.1.0
+Summary: Provider-independent SQL research with durable evidence
+Project-URL: Repository, https://github.com/JohnnyFiv3r/sourcesQL
+Project-URL: Documentation, https://github.com/JohnnyFiv3r/sourcesQL/blob/main/README.md
+Project-URL: Issues, https://github.com/JohnnyFiv3r/sourcesQL/issues
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: duckdb,mcp,sql,web-research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Requires-Python: <3.15,>=3.12
+Requires-Dist: duckdb==1.5.0
+Requires-Dist: httpx==0.28.1
+Requires-Dist: pyarrow==23.0.1
+Requires-Dist: pydantic-ai-slim[openai]==2.27.0
+Requires-Dist: pydantic==2.13.3
+Requires-Dist: sqlglot==30.19.0
+Provides-Extra: motherduck
+Requires-Dist: psycopg[binary]==3.3.3; extra == 'motherduck'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/JohnnyFiv3r/sourcesQL/main/assets/brand/sourcesql-mcp-icon.png" width="112" alt="sourcesQL logo">
+</p>
+
+# sourcesQL
+
+**Web research you can query, inspect and keep working with.**
+
+sourcesQL is an open-source research engine and MCP App. A connected assistant turns your request into SQL, searches the web, builds a structured dataset and presents the finished table in chat. You can inspect its sources, expand a row into a follow-up investigation, amend a field, review a later refresh and move the saved research between compatible installations.
+
+Use it when the answer needs rows: a vendor comparison, a project pipeline, an organization inventory or a collection of claims with supporting sources. The result stays available for further SQL instead of becoming another table trapped in a conversation.
+
+<p>
+  <a href="https://github.com/JohnnyFiv3r/sourcesQL/blob/main/LICENSE"><img alt="License: Apache 2.0" src="https://img.shields.io/badge/License-Apache%202.0-9AE4C2?style=flat-square&amp;labelColor=0E221D"></a>
+  <a href="https://github.com/JohnnyFiv3r/sourcesQL/blob/main/docs/python-linux-qualification.md"><img alt="Python: 3.12–3.14" src="https://img.shields.io/badge/Python-3.12%E2%80%933.14-9AE4C2?style=flat-square&amp;labelColor=0E221D"></a>
+</p>
+
+## Keep working with saved research
+
+Saved research includes the result, its supporting sources and the investigations that follow from it.
+
+- **Expand.** Choose a row or a field within it and ask a follow-up question. The findings open in a linked child table, with the research tree keeping the path back to the parent. For example, expand one company into a table of its announced facilities.
+- **Amend.** Correct a value and record why. Amendments have a separate revision history, so original observations stay available. Follow-up SQL can use the original result or a pinned amended view.
+- **Refresh.** Check a field, row or table again, then review the proposed changes. Explicitly accept supported updates or keep the current values; earlier observations and amendments remain available.
+- **Portable snapshots.** Export a research tree as a bundle and restore it in another compatible sourcesQL store. Bundles carry original results, sources, amendments, linked investigations and refresh decisions. Reopen saved findings without repeating web discovery.
+
+See the [research lifecycle](https://github.com/JohnnyFiv3r/sourcesQL/blob/main/docs/app-integration.md#contracts-and-lifecycle) and [snapshot/export contracts](https://github.com/JohnnyFiv3r/sourcesQL/blob/main/docs/app-integration.md#snapshots-presentation-and-export) for supported scopes, review behavior and bundle limits.
+
+## How research works
+
+The assistant plans the search terms. sourcesQL executes the query and keeps the data, evidence and execution receipt.
+
+1. **Discover broadly.** Use complementary search terms across terminology, source types and angles. Search results are candidate pages, not verified entities.
+2. **Reduce with SQL.** Merge overlapping results, deduplicate sources, filter available fields and join saved datasets before spending on semantic processing.
+3. **Extract selectively.** Apply semantic matching, extraction, scoring or normalization to candidates that still need it, using explicitly configured models.
+4. **Present the finished table.** Keep intermediate work behind the scenes. Open the final selection with readable labels, useful source links and an intentional row order.
+5. **Continue from saved research.** Reopen, query, correct, expand or refresh a result without repeating discovery unnecessarily.
+
+SQL filters run before semantic work where the admitted query plan permits it. A final `LIMIT` bounds returned rows; it does not make earlier search or model work cheaper.
+
+This query runs against the included **fictional fixtures**, with no API keys or network calls:
+
+```sql
+SELECT
+  SEM_EXTRACT(content, 'project name explicitly stated') AS project,
+  SEM_EXTRACT(
+    content,
+    'planned capacity in MW, number only',
+    type := 'DOUBLE'
+  ) AS planned_capacity_mw,
+  url AS source_url
+FROM WEB_SEARCH('fictional Aurora Birch campuses')
+WHERE SEM_MATCH(content, 'describes a specific data-center campus')
+ORDER BY project, source_url;
+```
+
+The engine supports `WEB_SEARCH`, `WEB_FETCH`, `SEM_MATCH`, `SEM_EXTRACT`, `SEM_EXTRACT_ALL`, `SEM_SCORE` and `SEM_NORM`. It accepts an explicit subset of DuckDB-style `SELECT` and nonrecursive `WITH` queries. See the [SQL reference](https://github.com/JohnnyFiv3r/sourcesQL/blob/main/docs/language.md) for signatures, supported staging and refusals. Operator availability also depends on the selected provider profile.
+
+## The interactive workspace
+
+The MCP App adds an interactive table to compatible clients, including ChatGPT. Use contextual table actions or ask the connected assistant to continue from a saved result. Linked tables are accessible through the research tree. Other MCP clients can use the same tools without rendering the app.
+
+The app decorates column labels and source addresses without rewriting data. Missing values stay missing. Search excerpts remain identified as excerpts, and a supporting quote establishes what a source says rather than proving the claim true.
+
+## Choose an installation
+
+| Path | You run | Best starting point |
+| --- | --- | --- |
+| **Local Docker** | App, MCP server and Python engine in containers; local persistent volumes | Try the workspace without installing Python or Node |
+| **Python / source checkout** | CLI or Python engine; optional Node app | Build queries, integrate the engine or develop the project |
+| **Personal cloud** | Vercel gateway, MotherDuck storage and Flights; OAuth for ChatGPT | Use a hosted MCP endpoint without keeping Docker running |
+
+Every path starts in **fixture mode**. Live search and model calls require credentials, an enabled trusted profile and explicit execution budgets.
+
+### Local Docker
+
+Clone this repository and run from its root with Docker running:
+
+```sh
+git clone https://github.com/JohnnyFiv3r/sourcesQL.git
+cd sourcesQL
+docker compose up --build -d sourcesql-app
+```
+
+Open **[localhost:3117](http://127.0.0.1:3117)**. The initial workspace uses synthetic data. Its named volume preserves results and corrections across restarts.
+
+To connect a local MCP client over stdio, first build the app image:
+
+```sh
+docker compose build sourcesql-mcp
+```
+
+Then configure the client to run `docker compose run --rm -T --no-deps sourcesql-mcp` from this checkout. The [Docker guide](https://github.com/JohnnyFiv3r/sourcesQL/blob/main/docs/docker.md#mcp-over-stdio) includes a complete MCP configuration, storage details and the CLI container. The default stdio container has no network; live providers require deliberate network and credential configuration.
+
+A local endpoint alone is not reachable by hosted ChatGPT. Use the hosted path below for a remotely accessible, authenticated connection.
+
+### Python and CLI
+
+Install with Python 3.12–3.14 on macOS or Linux:
+
+```sh
+python -m pip install sourcesql
+sourcesql --store ./research-data demo --output ./research-demo
+sourcesql --store ./research-data capabilities --json
+```
+
+The installed demo includes fictional sources and needs no credentials or checkout. Each successful query returns an immutable `result_id`, typed columns, a bounded row preview and an execution receipt. Use the ID printed by `demo` to reopen or export it:
+
+```sh
+sourcesql --store ./research-data read RESULT_ID --offset 0 --limit 100
+sourcesql --store ./research-data export --result RESULT_ID --output result-bundle.json
+sourcesql --store ./restored import result-bundle.json --no-network
+```
+
+For source development, clone this repository, install [uv](https://docs.astral.sh/uv/) and run `uv sync --frozen`. Then use `uv run sourcesql` in place of `sourcesql`. See [package installation and release checks](https://github.com/JohnnyFiv3r/sourcesQL/blob/main/docs/package.md).
+
+For Python integration, import `Engine` from `sourcesql.engine`. The [examples](https://github.com/JohnnyFiv3r/sourcesQL/blob/main/examples/) cover discovery, saved-result refinement, row expansion and snapshot comparison.
+
+To run the app from source, install **Node.js 24**, prepare the root Python environment with `uv sync --frozen`, then run:
+
+```sh
+cd apps/research
+npm ci
+npm run build
+npm start
+```
+
+Open [localhost:3117](http://127.0.0.1:3117), or use `npm run stdio` with a local MCP client. See the [example client configuration](https://github.com/JohnnyFiv3r/sourcesQL/blob/main/apps/research/mcp-config.example.json). CLI and app stores are separate by default; use the MCP query/result-reference workflow for app research, or research bundles to move it between stores.
+
+Actual SQL execution requires the supported OS protections: macOS `sandbox-exec`, or Linux Landlock and seccomp. Missing protection causes a refusal. Use Docker on Windows. See [runtime qualification](https://github.com/JohnnyFiv3r/sourcesQL/blob/main/docs/python-linux-qualification.md) for the tested environments.
+
+### Personal cloud: Vercel + MotherDuck
+
+This path uses your own accounts and one owner workspace:
+
+```text
+ChatGPT / MCP client
+        │
+        ▼
+Vercel: MCP tools, app UI, authentication
+        │
+        ▼
+MotherDuck: saved research, evidence, corrections, jobs
+        │
+        └── on-demand Flight: Python research execution
+```
+
+Ordinary reads, tree navigation and corrections use stored records without starting Python. Research runs as a bounded asynchronous job. One job runs at a time per owner namespace; queued jobs resume explicitly. A lost response is recovered using the same request and job IDs.
+
+The installed package includes guided setup:
+
+```sh
+sourcesql setup personal-cloud --help
+sourcesql setup personal-cloud plan --config personal.json --workspace ./my-cloud
+sourcesql setup personal-cloud apply --workspace ./my-cloud --approve-plan PLAN_SHA256
+```
+
+Follow the [personal-cloud setup guide](https://github.com/JohnnyFiv3r/sourcesQL/blob/main/docs/personal-cloud-setup.md) to prepare your accounts, owner identity and token-free configuration. The plan records the exact destination, public source hashes, execution policy and proposed changes before applying them. Repeating an approved plan recovers its saved resources; uncertain creation stops for inspection.
+
+Setup provisions a Vercel Preview gateway and a bounded MotherDuck Flight. It keeps credentials server-side, defaults to fixture mode and leaves account creation, OAuth registration and the exact-domain protection exception as visible account steps. Verify one fixture job and reopen its stored result before enabling live research. The [client guide](https://github.com/JohnnyFiv3r/sourcesQL/blob/main/docs/clients.md) covers ChatGPT, Claude and Cursor, including which host interactions have actually been qualified.
+
+Eligible personal, non-commercial adopters can choose Vercel Hobby; no Pro-only feature is required by this configuration. MotherDuck, search and model consumption are separate. Included allowances may cover light use, but application budgets do not guarantee that a platform account with billing enabled stops before overage.
+
+## Configure live search and models
+
+Start with the [provider guide](https://github.com/JohnnyFiv3r/sourcesQL/blob/main/docs/providers.md) and [profile template](https://github.com/JohnnyFiv3r/sourcesQL/blob/main/examples/profiles.example.json). Keep real configuration and secrets outside version control.
+
+| Capability | Configuration |
+| --- | --- |
+| Local live search | Exa, Brave or Serper adapter; its API key, live permission and finite budget |
+| Semantic extraction / matching / normalization | An explicitly named model and its credential |
+| Semantic scoring | An explicitly configured embedding adapter |
+| Hosted Exa, Brave or Serper | Choose one live provider per reviewed Flight; bind its secret and matching gateway policy |
+
+For search-only work, omit model and embedding settings. An Exa API key does not enable semantic operators or authorize spending. Request budgets must fit the trusted profile; source fetching also requires approved destination hosts.
+
+The existing owner deployment’s qualified hosted profile, **`exa-search.v1`**, uses Exa Auto and retained excerpts. It permits **two searches and ten candidate pages per job**, with no extra fetches or model calls. It is a small search-only configuration, not broad entity-research capacity. Larger fanout and semantic research need separately configured and qualified execution profiles. The [hosted provider guide](https://github.com/JohnnyFiv3r/sourcesQL/blob/main/docs/providers-hosted.md) describes the new Brave/Serper options and their qualification limits; see also the [hosted policy](https://github.com/JohnnyFiv3r/sourcesQL/blob/main/docs/hosted-flight.md#opt-in-exa-search) and [Exa research notes](https://github.com/JohnnyFiv3r/sourcesQL/blob/main/docs/exa-research.md).
+
+## Status and development
+
+The project includes the Python package, local Docker app, guided personal-cloud setup, durable MotherDuck jobs and storage, and hosted ChatGPT OAuth/app rendering. Fixture tests, live provider quality and host integration are different checks; the [current status](https://github.com/JohnnyFiv3r/sourcesQL/blob/main/STATUS.md) records their scope and remaining gaps. Broad live research quality, hosted semantic models and Claude rendering are not qualified by the small Exa integration.
+
+Run local checks from the repository root:
+
+```sh
+uv run pytest -q
+npm ci --prefix apps/research
+npm --prefix apps/research run check
+```
+
+Positive SQL worker tests need permission to launch the OS sandbox. A sandbox refusal is not a passing execution test. See [qualification](https://github.com/JohnnyFiv3r/sourcesQL/blob/main/docs/qualification.md) and [app integration](https://github.com/JohnnyFiv3r/sourcesQL/blob/main/docs/app-integration.md) for the execution, evidence and storage contracts.
+
+The [roadmap](https://github.com/JohnnyFiv3r/sourcesQL/blob/main/docs/roadmap.md) puts compact research checkpoints and manual evidence-backed updates after adoption. These extend saved research; they are planned capabilities.
+
+Licensed under [Apache 2.0](https://github.com/JohnnyFiv3r/sourcesQL/blob/main/LICENSE). Attribution and source reuse are recorded in [NOTICE](https://github.com/JohnnyFiv3r/sourcesQL/blob/main/NOTICE) and [provenance](https://github.com/JohnnyFiv3r/sourcesQL/blob/main/provenance/).