hypothesis-generation 0.5.0__tar.gz

hypothesis_generation-0.5.0/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+## Unreleased
+
+No unreleased changes.
+
+## 0.5.0 — 2026-09-01
+
+- Renamed the executable-theory Python API to the canonical
+  `HypothesisGeneration*` symbols, including discovery, capability, ledger,
+  freeze, and benchmark helpers.
+- Added bounded multi-step premise programs across eighteen typed
+  transformation families.
+- Added exact persistent hypothesis campaigns with deterministic pages,
+  tamper-evident cursors, and honest pre-page exhaustion.
+- Added balanced, diversity-, novelty-, plausibility-, testability-, and
+  caller-defined portfolio objectives.
+- Added dependency-free BM25, declared aliases, metadata and date views,
+  relation overlap, and in-memory/SQLite prior-art parity.
+- Added content-bound extension bundles, fail-closed verification, a bounded
+  subprocess harness, and generalized replay-addressed handoffs.
+- Added domain-pack scaffolds and review packets for reliability engineering,
+  materials/process engineering, and systems biology.
+- Added independent holdout commitments, blind pairwise evaluation materials,
+  field-stratified reports, and prospective prediction records.
+- Added bounded multi-elite retention, declared-alias normalization, and
+  constrained missing-bridge invention.
+- Added exact portfolio optimization and deterministic recursive symbolic
+  search with validation-selected shallow/recursive portfolios.
+- Added pinned offline adapters and qualification summaries for HypoSpace,
+  HypoBench, DiscoveryBench, and SRSD-Feynman.
+- Added the dated External Premise Challenge with hidden targets, fixed
+  baselines, adversarial controls, and anonymous review materials.
+- Added a nine-case release-qualification suite covering the public v0.5
+  contracts. All nine controls pass.
+- Preserved the v0.3 typed API and the dependency-free core, with no LLM or
+  network access at runtime.
+
+## 0.4.0 — 2026-08-31
+
+- Added the phenomenon-first API with English hypotheses as the default output.
+- Added fourteen extensible reasoning modes and typed premise-invention
+  artifacts with generate-test-constrain search and quality-diversity
+  selection.
+- Added structured concepts, relations, observations, contexts, constraints,
+  analogy sources, prior hypotheses, declarative domain packs, and candidate
+  provenance.
+- Added in-memory and SQLite/FTS5 prior-art indexes, persistent artifact
+  ledgers, discriminating tests, and sealed temporal evaluation.
+- Added bounded APIs for abduction, theory revision, counterexamples,
+  dimensional analysis, equation search, mechanisms, causal structures,
+  experiment design, and optional solver/scientific-computing adapters.
+- Added executable-theory generation with finite worlds, representation
+  invention, executable theory synthesis, holdout isolation, theory
+  quality-diversity, and counterfactual revision cycles.
+- Added schemas, agent protocol support, domain-pack review contracts,
+  field-stratified evaluation, and end-to-end release qualification.
+- Preserved the v0.3 typed request, response, CLI, hashes, and numeric evaluator.
+
+## 0.3.0 — 2026-08-29
+
+- Added typed mathematical model contracts, exact support ranges, request IDs,
+  dimensional constraints, and deterministic family selection.
+- Added scalar, Boolean, multivariate, transition, interaction, and temporal
+  model families with predictions and falsifiers.
+- Added numeric evaluation for supported relation families without fitting
+  parameters or reading data.
+- Added strict schemas, capabilities, duplicate-key rejection, bounded inputs,
+  packaging, CI, security guidance, and structural benchmarks.

hypothesis_generation-0.5.0/CITATION.cff

@@ -0,0 +1,14 @@
+cff-version: 1.2.0
+title: "Deterministic Hypothesis Generation"
+message: "If this software contributes to your work, please cite the repository."
+type: software
+authors:
+  - family-names: Dimurro
+    given-names: Chris
+version: 0.5.0
+date-released: 2026-09-01
+repository-code: "https://github.com/cdimurro/hypothesis-generation"
+license: Apache-2.0
+abstract: >-
+  A deterministic engine that constructs typed, testable hypothesis candidates
+  from declared scientific knowledge and constraints without using LLMs.

hypothesis_generation-0.5.0/CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing
+
+Contributions should preserve the project's central contract: hypotheses are
+generated by reproducible code with zero LLM calls, no hidden network access,
+and no claim authority. The legacy typed core remains declaration-only. The
+discovery layer may inspect only caller-supplied facts, observations, relation
+edges, or explicit offline prior-art indexes.
+
+## Development
+
+```powershell
+python -m pip install -e ".[test]"
+$env:PYTHONPATH = "src"
+python -m pytest -q
+python -m ruff check src tests scripts examples
+python -m ruff format --check src tests scripts examples
+python scripts/verify_release.py
+```
+
+Add a clean control and a planted dirty control for every new parser check,
+eligibility rule, or safety guard. Add deterministic tests for every new
+grammar family, including its variable kinds, units, parameter constraints,
+shortfall behavior, and agent-protocol representation.
+
+Do not add learned ranking, hidden corpus access, network calls, observation
+inputs, fitted values, or callbacks to the legacy core request path. Hypothesis
+strategies must keep their input provenance explicit and must not introduce
+model clients or prose generation as hidden dependencies.
+
+The 14 discovery modes are not a mode-count contest. New premise strategies
+must define their typed inputs, graph operation, concept operator, prospective
+fields, non-applicability behavior, provenance, structural cell, and ablation.
+Do not disguise a canned sentence as premise invention. Keep optional solvers,
+numerical libraries, scientific file formats, and non-LLM machine learning
+behind explicit caller-supplied adapter
+contracts with version, configuration, seed, environment, and data-partition
+fingerprints.
+
+Domain knowledge belongs in an explicitly selected declarative pack, not in
+keyword rules in the neutral core. A reference-pack contribution needs an
+exact-digest release manifest, positive and negative fixtures, competency
+results, version history, license review, and genuine independent `DOMAIN` and
+`SOFTWARE_FORMALISM` approvals. Tests may exercise synthetic or draft review
+records, but maintainers must never invent people or approvals for a release.
+Generative vocabulary must remain data-only, source-attributed, and unusable by
+generation until the pack has completed both review roles. Executable hooks and
+canned hypothesis fields are prohibited.
+
+Any evaluation contribution must declare the task population, baselines,
+controls, cutoff policy, calibration status, and non-claims. Preserve blind
+packets until ratings are locked. Keep results field-stratified and do not turn
+structural pass rates or heuristic selection scores into a universal
+scientific-quality score.
+
+## Pull requests
+
+Explain the scientific scope of each new family, its assumptions, the
+prospective prediction, the falsifier, and any limits on numeric evaluation.
+Do not describe deterministic generation as proof of novelty, truth, causality,
+or experimental support. Update the changelog and schemas when the public
+contract changes. Run `python scripts/verify_release.py` before requesting
+review; it performs local-input-only package qualification and must stay green.

hypothesis_generation-0.5.0/LICENSE

@@ -0,0 +1,201 @@
+                                 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.

hypothesis_generation-0.5.0/MANIFEST.in

@@ -0,0 +1,12 @@
+include CHANGELOG.md
+include CITATION.cff
+include CONTRIBUTING.md
+include LICENSE
+include NOTICE
+include README.md
+include SECURITY.md
+recursive-include benchmarks *.json *.md
+recursive-include docs *.md
+recursive-include examples *.json
+recursive-include examples *.py
+recursive-include schemas *.json

hypothesis_generation-0.5.0/NOTICE

@@ -0,0 +1,4 @@
+Deterministic Hypothesis Generation
+Copyright 2026 Chris Dimurro
+
+This product is distributed under the Apache License, Version 2.0.

hypothesis_generation-0.5.0/PKG-INFO

@@ -0,0 +1,280 @@
+Metadata-Version: 2.4
+Name: hypothesis-generation
+Version: 0.5.0
+Summary: Deterministic premise invention and hypothesis generation without LLMs.
+Author: Chris Dimurro
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/cdimurro/hypothesis-generation
+Project-URL: Repository, https://github.com/cdimurro/hypothesis-generation
+Project-URL: Issues, https://github.com/cdimurro/hypothesis-generation/issues
+Project-URL: Documentation, https://github.com/cdimurro/hypothesis-generation#readme
+Keywords: science,hypothesis,research,deterministic,agents
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Provides-Extra: test
+Requires-Dist: pytest<9,>=8; extra == "test"
+Requires-Dist: ruff<0.16,>=0.15; extra == "test"
+Requires-Dist: jsonschema<5,>=4; extra == "test"
+Requires-Dist: build<2,>=1; extra == "test"
+Requires-Dist: setuptools>=77; extra == "test"
+Dynamic: license-file
+
+# Hypothesis Generation
+
+**Generate novel, testable hypotheses without an LLM.**
+
+Hypothesis Generation is a deterministic, programmable engine for scientists,
+engineers, mathematicians, and research software teams. It constructs candidate
+hypotheses from explicit observations, concepts, relations, constraints,
+mechanisms, analogies, and domain knowledge.
+
+The engine runs locally. It has no runtime model dependency, makes no network
+requests, and does not sample from a pretrained distribution. The same request,
+engine version, extension set, domain pack, and corpus snapshot produces the
+same result.
+
+## Why it is different
+
+Language models generate text from learned statistical patterns. This project
+uses typed transformations, finite formal reasoning, constraint checks, bounded
+search, and quality-diversity selection to construct hypotheses that were not
+supplied as templates.
+
+That makes each result reproducible and inspectable:
+
+- domain facts come only from declared inputs, traceable corpora, formal rules,
+  or reviewed domain packs;
+- invalid candidates can be rejected by explicit type, logic, graph,
+  dimensional, contradiction, and mechanism checks;
+- requested portfolios are selected for structural coverage instead of padded
+  with paraphrases;
+- novelty diagnostics are always relative to an identified corpus; and
+- derivations, scores, provenance, tests, and archives are available when a
+  caller requests them.
+
+The engine proposes candidates for investigation. Experiments, prior-art
+review, safety review, and scientific judgment remain external responsibilities.
+
+## Install
+
+Python 3.10 or later is required. The core has no runtime dependencies.
+
+```powershell
+python -m pip install -e .
+```
+
+The repository version can also be installed directly:
+
+```powershell
+python -m pip install "hypothesis-generation @ git+https://github.com/cdimurro/hypothesis-generation.git"
+```
+
+## Quick start
+
+The common API requires a phenomenon and a count:
+
+```python
+from hypothesis_generation import generate_hypotheses
+
+hypotheses = generate_hypotheses(
+    "urban heat islands remain hotter overnight after heat waves",
+    count=8,
+)
+
+for hypothesis in hypotheses:
+    print(hypothesis)
+```
+
+The default output is a list of English hypotheses. Backend artifacts remain
+hidden unless explicitly requested.
+
+The equivalent command-line request is:
+
+```json
+{
+  "phenomenon": "urban heat islands remain hotter overnight after heat waves",
+  "count": 8
+}
+```
+
+```powershell
+python -m hypothesis_generation --input request.json --pretty
+```
+
+## Add scientific structure
+
+More explicit inputs produce more specific hypotheses:
+
+```python
+from hypothesis_generation import ConceptSpec, DiscoveryRequest, RelationSpec, discover
+
+request = DiscoveryRequest(
+    phenomenon="nighttime cooling slows after a heat wave",
+    count=4,
+    concepts=(
+        ConceptSpec("impervious surface fraction", "DRIVER"),
+        ConceptSpec("stored subsurface heat", "MEDIATOR"),
+        ConceptSpec("nighttime cooling rate", "OUTCOME"),
+    ),
+    relations=(
+        RelationSpec(
+            "impervious surface fraction",
+            "increases",
+            "stored subsurface heat",
+        ),
+    ),
+)
+
+result = discover(request)
+print(result.as_dict())
+```
+
+Requests can also declare known facts, observations, contexts, constraints,
+prior hypotheses, analogy sources, causal structures, quantities, domain packs,
+and a frozen prior-art corpus. Undeclared synonyms and domain facts are never
+guessed.
+
+See [the discovery API](docs/DISCOVERY.md) for request fields, response
+projection, search budgets, persistence, and exhaustion behavior.
+
+## How generation works
+
+1. **Normalize the request.** Convert declared knowledge into typed concepts,
+   relations, constraints, mechanisms, quantities, and provenance records.
+2. **Invent premises.** Apply typed transformations and bounded multi-step
+   programs to propose mechanisms, missing bridges, alternatives, boundary
+   conditions, analogies, interventions, and counterexamples.
+3. **Generate candidates.** Explore fourteen complementary reasoning modes.
+4. **Test and constrain.** Reject candidates that fail applicable formal or
+   declared scientific checks.
+5. **Check prior art.** Compare candidates with a frozen local corpus using
+   exact, lexical, BM25, relation, and structural diagnostics.
+6. **Select a portfolio.** Optimize quality and structural coverage under a
+   declared ranking profile.
+7. **Render the result.** Return English hypotheses by default and only the
+   requested artifact fields when details are needed.
+
+The fourteen public modes cover causal, abductive, temporal, systems, regime,
+heterogeneity, measurement, invariant, contrastive, intervention, null-model,
+relational, analogical, and compositional reasoning. They are search strategies
+over one integrated premise-invention system, not sentence templates.
+
+## Large hypothesis campaigns
+
+Persistent campaigns can generate exact portfolios of up to 10,000 unique
+hypotheses when the admitted search pool is large enough. Results are returned
+through deterministic, tamper-evident pages. If the requested total cannot be
+produced without duplicates or cosmetic rewrites, the campaign reports search
+exhaustion before returning a partial result.
+
+Portfolio profiles include:
+
+- `BALANCED`
+- `DIVERSITY_FIRST`
+- `NOVELTY_FIRST`
+- `PLAUSIBILITY_FIRST`
+- `TESTABILITY_FIRST`
+- bounded caller-declared custom weights
+
+Profiles change transparent ranking objectives; they do not load a learned
+ranking model.
+
+## Prior-art comparison
+
+The optional local prior-art index supports exact overlap, phrase containment,
+token similarity, Okapi BM25, declared aliases, relation overlap, metadata
+filters, date-bounded corpus views, and SQLite/FTS5 storage.
+
+These diagnostics answer whether a candidate overlaps the supplied corpus.
+They do not claim exhaustive or universal novelty.
+
+## Program it for an application
+
+There are two extension paths:
+
+- **Domain packs** add reviewed, data-only concepts, relations, rules, sources,
+  aliases, constraints, and generative vocabulary.
+- **Extension bundles** add deterministic application code through
+  content-addressed manifests that bind source files, dependencies, and runtime
+  policy.
+
+Starter domain-pack scaffolds are available for engineered-system reliability,
+materials/process engineering, and systems biology:
+
+```powershell
+hypothesis-generate --scaffold-domain-pack materials-process-engineering `
+  --output-directory packs/materials-process
+```
+
+Scaffolds contain no facts or approvals and remain `AWAITING_REVIEW` until the
+completed digest receives the required reviews. See [domain packs](docs/DOMAIN_PACKS.md)
+and [extensions](docs/EXTENSIONS.md).
+
+Optional scientific-computing and formal-solver adapters can be supplied by a
+caller. They are never discovered, installed, or invoked implicitly.
+
+## Evaluation
+
+The repository includes structural, historical, cross-domain, external, and
+negative-control benchmarks. Selected pinned results are:
+
+| Evaluation | Result | Scope |
+|---|---:|---|
+| Release qualification | 9/9 controls | Runtime boundary, campaigns, ranking, novelty, extensions, packs, evaluation, and legacy behavior |
+| HypoSpace | 441/441 admissible targets | 88 Boolean, causal-graph, and voxel cases |
+| HypoBench synthetic | 1,450/1,500 held-out rows | Nine classification cases |
+| HypoBench real-world | 2,003/3,100 held-out; 1,431/2,593 OOD | Seven text-classification tasks |
+| DiscoveryBench expanded | 8/24 strong; median sealed-test R-squared 0.727 | Systematic synthetic task sample |
+| SRSD-Feynman portfolio | 37/50 strong; median test R-squared 0.876 | Recursive symbolic search with sealed test rows |
+| External Premise Challenge | 11/12 generated and admitted; 5/12 public top-10 | Dated historical diagnostic across six fields |
+
+These measurements apply only to the pinned files, grammars, budgets, and
+evaluation rules. They are not estimates of general scientific truth or expert
+preference. External metrics that require an LLM judge are reported as not run.
+
+See [the benchmark guide](benchmarks/README.md), [evaluation kit](docs/EVALUATION_KIT.md),
+and [scientific limitations](docs/SCIENTIFIC_LIMITATIONS.md).
+
+## Release status
+
+Version 0.5 is a public beta. The deterministic core, packaging, compatibility,
+and benchmark contracts are qualified; the complete suite passes 538 tests.
+Version 1.0 is reserved for stable contracts informed by independent users,
+reviewed reference domain packs, blind expert evaluation, and prospective
+evidence in multiple fields.
+
+The legacy v0.3 typed mathematical-model API remains supported. See
+[release readiness](docs/RELEASE_READINESS.md), [release qualification](docs/RELEASE_QUALIFICATION.md),
+and the [release plan](docs/RELEASE_PLAN.md).
+
+## Documentation
+
+Start with the [documentation index](docs/README.md). Important references are:
+
+- [Architecture and runtime boundary](docs/DESIGN.md)
+- [Discovery API](docs/DISCOVERY.md)
+- [Domain packs](docs/DOMAIN_PACKS.md)
+- [Application extensions](docs/EXTENSIONS.md)
+- [Agent protocol](docs/AGENT_PROTOCOL.md)
+- [Scientific capabilities and limitations](docs/SCIENTIFIC_LIMITATIONS.md)
+- [Release qualification](docs/RELEASE_QUALIFICATION.md)
+
+## Contributing
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) before adding an operator, family,
+domain pack, adapter, or benchmark. Security guidance is in
+[SECURITY.md](SECURITY.md).
+
+Hypothesis Generation is released under the [Apache License 2.0](LICENSE).