researchos-ci 0.4.0__tar.gz

researchos_ci-0.4.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Virtualenvs
+.venv/
+venv/
+
+# OS/editor
+.DS_Store
+.idea/
+.vscode/
+
+# Local secrets and env
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+
+# Generated demo artifacts
+.researchos/
+dist/
+examples/quant-failing-pr/results/
+examples/quant-failing-pr/researchos-verdict.txt

researchos_ci-0.4.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.

researchos_ci-0.4.0/NOTICE

@@ -0,0 +1,9 @@
+ResearchOS / Research CI
+
+This repository is an original Research CI MVP inspired by the public Apache-2.0
+get-physics-done project from Physical Superintelligence PBC (PSI):
+https://github.com/psi-oss/get-physics-done
+
+No GPD source files are vendored in this MVP. Before extracting or adapting GPD
+source directly, preserve Apache-2.0 license/notice obligations and complete a
+provenance/dependency audit.

researchos_ci-0.4.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.5
+Name: researchos-ci
+Version: 0.4.0
+Summary: Research CI verifier with evidence-bound quant and ML domain checks
+Project-URL: Repository, https://github.com/demirelo/researchos
+Project-URL: Issues, https://github.com/demirelo/researchos/issues
+Author: ResearchOS
+License: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# ResearchOS / Research CI
+
+**Verify claims and evidence in AI-assisted computational research.**
+
+Research CI is the main product. It checks declared claims, linked evidence,
+domain rules and optional reproduction before a research change passes CI.
+The optional Conductor adds approved Builder steps and independent review around
+that verification gate.
+
+A passing configuration check is separate from a reproduced, supported claim.
+The verdict `proved` means a declared computational predicate passed the configured
+checks. It does not establish general scientific truth.
+
+## Implementation status
+
+Version **0.4.0** extends the implementation of all 12 improvement ideas from
+[the proposal](https://researchos-10x-ideas-jai3.pages.grok.bot/).
+[PR #16](https://github.com/demirelo/researchos/pull/16) merged the initial implementation.
+This update completes the remaining code features and adds publishing workflows.
+Registry publication and public report deployment remain separate service actions.
+
+| Idea | Current implementation | Operating limit |
+|---|---|---|
+| GitHub Action | Sticky PR comment, Check Run, line annotations, job summary and report artifacts | Code scanning must be enabled before GitHub can accept SARIF uploads |
+| Finding guidance | Shared reasons, required actions, config examples, `explain` and print-only `--fix` | Suggested fixes require review; they do not create evidence |
+| Packaged domain packs | Quant and ML resources, verified wheel/source builds and GitHub/PyPI release workflow | PyPI requires the owning account to configure its trusted publisher |
+| Claim extraction | Draft claims from Markdown, notebook Markdown and PR text; optional model review | Claims remain proposed until a person reviews them and links evidence |
+| Reproduction | Explicit Docker execution, fresh outputs, timeouts and authenticated cache for pinned image digests | Experiments must supply their dependencies and reproduction scripts |
+| Evidence binding | Scalar and interval predicates, percentile/basic bootstrap, tolerances, artifact hashes and fresh-result comparison | Sampling assumptions and interval coverage require review |
+| Verdict semantics | Supported reproduced keystones can be terminal; valid contradictory results can be falsified | Skipped reproduction and legacy self-attestations remain non-terminal |
+| Builder loop | Approved worktree edits, Venice and Claude Code adapters, independent review, new verification and iteration checkpoints | Custom adapters must enforce their provider budget |
+| Quant checks | Typed assumptions, bounded def/use dataflow, computed pairing permutation controls and advisory deflated Sharpe | Dynamic Python flows and experiment refits require explicit project protocols |
+| Reports and badge | Static reports, HTTP report/badge endpoint, checksummed sites and Pages deployment workflow | [Synthetic demo is live](https://demirelo.github.io/researchos/); real reports require an approved destination |
+| ML and pack SDK | Split hashes/membership, seed results, baseline parity and 12 declarative SDK operators for config or reproduced metrics | Custom fixture execution requires an explicit Docker or trusted-host flag |
+| Event and CLI consistency | Incremental reads, persisted settings, redirects, request recovery and durable cost records | Uncertain paid attempts require reconciliation before retry |
+
+See the [implementation and validation record](docs/IMPLEMENTATION_10X.md) for
+check details and the [workflow guide](docs/USAGE_10X.md) for configuration.
+
+## Requirements and installation
+
+Use Python **3.11+**. The examples below use [`uv`](https://docs.astral.sh/uv/).
+Docker must be running when you request container reproduction. Prepare an image
+with the experiment dependencies; reproduction does not install them.
+
+```bash
+git clone https://github.com/demirelo/researchos.git
+cd researchos
+uv sync
+uv run researchos --version
+```
+
+Build and install a local wheel:
+
+```bash
+uv build --clear
+python3.11 -m venv /tmp/researchos-venv
+/tmp/researchos-venv/bin/python -m pip install dist/researchos_ci-0.4.0-py3-none-any.whl
+/tmp/researchos-venv/bin/researchos --version
+```
+
+The distribution name is `researchos-ci`; the command and Python import remain
+`researchos`. The wheel includes both domain packs. Version 0.4.0 was built and tested locally;
+this change does not publish it to PyPI or create a downloadable release.
+
+## Verify a project
+
+```bash
+uv run researchos verify --ci examples/quant-failing-pr
+```
+
+The bundled quant fixture is deliberately incomplete. Expect a non-zero exit
+and blocking findings. Verification does **not execute project code by default**.
+
+Request restricted Docker reproduction explicitly:
+
+```bash
+uv run researchos verify --ci --reproduce --timeout 600 \
+  --image python:3.12-slim /path/to/project
+```
+
+Docker reproduction disables network access, removes inherited environment
+variables, uses a read-only root filesystem and enforces resource limits.
+Pin the image digest to enable authenticated reproduction caching.
+`--unsafe-local` runs trusted project code on the host with no filesystem or
+network isolation.
+
+Declare claims and evidence in `researchos.yaml`. Supply a reproduction script
+and fresh output files when you need a reproduced verdict. See
+[structured claims and reproduction](docs/USAGE_10X.md) and
+[statistical evidence and controls](docs/STATISTICAL_CHECKS.md).
+
+## Extract claims, inspect findings and generate reports
+
+```bash
+uv run researchos init /path/to/project --domain ml
+uv run researchos explain quant.transaction_costs_present
+uv run researchos verify --ci --json-output verdict.json /path/to/project
+uv run researchos report verdict.json --output report/index.html \
+  --badge-output report/claims.svg
+uv run researchos pack test quant-finance
+uv run researchos pack test ml
+```
+
+`init` writes `researchos.draft.yaml` with proposed claims and candidate result
+files. Review the draft and link measured evidence before accepting it.
+`--fix` prints configuration examples for review; it does not edit the project
+or invent measurements. Reports and badges remain local until you publish them.
+Serve a live report and badge with `researchos report verdict.json --serve`, or
+create a deployment directory with `--site-dir public-report`. See
+[report hosting and releases](docs/PUBLISHING.md) and the
+[pack rule reference](docs/PACK_RULES.md).
+
+## GitHub integration
+
+The [composite Action](docs/GITHUB_ACTION.md) verifies a project and can publish
+one sticky bot comment, a Check Run and line annotations. It also writes JSON,
+SARIF, Markdown, HTML and SVG files for artifact upload. Fork PRs receive no
+privileged publication or project-code execution.
+
+The repository workflows check tests, secrets, repository hygiene and the
+expected-failure fixture. A separate maintainer smoke workflow tests a synthetic
+project. Its comment and Check Run use a separate identity so that fixture
+success cannot replace a project verdict.
+
+Code scanning is disabled for this repository as of 6 November 2026. SARIF remains
+available in report artifacts; the smoke workflow skips code-scanning upload
+when the service is unavailable.
+
+## Optional Conductor and model providers
+
+The Conductor records verification results, model proposals, director decisions,
+Builder diffs, review results and costs in an append-only event log.
+Venice is the primary documented model path. Set `VENICE_API_KEY` through your
+environment, an ignored `.env`/`.env.local`, or the supported macOS Keychain entry.
+Do not put credentials in prompts, commits or logs.
+
+Start a model-assisted planning run:
+
+```bash
+uv run researchos conductor start --project /path/to/project \
+  --goal 'Resolve the reproduction blocker' \
+  --mode venice --model qwen3-235b-a22b-instruct-2507 --budget-usd 2
+uv run researchos conductor progress
+uv run researchos conductor approve next
+```
+
+Planning alone does not configure a coding agent. For approved file edits and
+independent review, configure both native adapters:
+
+```bash
+uv run researchos conductor start --project /path/to/project \
+  --goal 'Resolve the reproduction blocker' \
+  --mode venice --model qwen3-235b-a22b-instruct-2507 \
+  --builder-command '["/ABS/VENV/bin/python","-m","researchos.conductor.venice_adapter"]' \
+  --adversary-command '["/ABS/VENV/bin/python","-m","researchos.conductor.venice_adapter"]' \
+  --allow-project-code-execution --budget-usd 2 --iteration-limit 2 \
+  --execution-timeout 600
+uv run researchos conductor approve next
+```
+
+Use an absolute path to the Python environment that contains ResearchOS.
+The native Venice adapter loads in isolated mode, receives only its scoped
+provider credential, and applies structured file edits. It does not execute
+model-proposed commands. Docker reproduction runs separately without that key.
+Each further iteration requires approval. No automatic commit or merge occurs.
+
+Venice costs derived from the live catalog are labelled estimates, not invoices.
+Missing usage or uncertain completions stop further work for reconciliation.
+OpenRouter PI calls and a Claude Code Builder/reviewer adapter are also supported.
+See the [Builder and provider guide](docs/USAGE_10X.md).
+
+`--mode fake` provides deterministic planning guidance with no model calls. Its
+STORM-style events are checklists, not independent model research. Live independent
+review requires a configured review adapter.
+
+## Agent guidance
+
+```bash
+uv run researchos skill install claude
+uv run researchos skill install codex --dest .
+```
+
+These installers provide guidance for running ResearchOS before an agent reports
+research progress. They do not make unsupported claims pass verification.
+
+## Validation
+
+Version 0.4.0 passed **156 local tests**, including clean-wheel installation,
+resampling, interval verdicts, SDK rules, dataflow, HTTP and release regressions.
+Astra reviewed the code at medium effort through the local CLI. Six findings
+were corrected; the closure review found no blocking findings. See the
+[completion record](docs/COMPLETION_PLAN.md).
+
+Live checks passed Docker isolation and cache reuse, Venice claim-draft review,
+Venice Builder/reviewer execution, conservative Claude review rejection, and
+GitHub comment/check updates, warning annotations and downloaded report artifacts.
+These checks used synthetic projects. They verify the software workflow, not
+real financial or scientific performance.
+
+## Project documents
+
+- [Workflow and configuration guide](docs/USAGE_10X.md)
+- [GitHub Action setup](docs/GITHUB_ACTION.md)
+- [Implementation and validation record](docs/IMPLEMENTATION_10X.md)
+- [Statistical evidence and controls](docs/STATISTICAL_CHECKS.md)
+- [Pack rule reference](docs/PACK_RULES.md)
+- [Report hosting and releases](docs/PUBLISHING.md)
+- [Positioning](docs/POSITIONING.md)
+- [Domain pack specification](docs/DOMAIN_PACK_SPEC.md)
+- [Open-core boundary](docs/OPEN_CORE_BOUNDARY.md)
+- [Research Conductor design](docs/RESEARCH_CONDUCTOR.md)
+- [STORM integration design](docs/STORM_INTEGRATION.md)