Research OS

• 

  Research OS

Research OS

Research OS is a governed AI research workspace that turns source material into an inspectable chain of evidence, claims, analysis, verification, and a final publication. Instead of returning an answer with no visible reasoning trail, it preserves the research lineage and produces a tamper-evident receipt for the run.

Inspiration

Modern AI can produce research remarkably quickly, but speed does not automatically create trust. Sources become detached from claims, important decisions disappear into chat history, and polished outputs can hide uncertainty. Teams are left with an answer but no durable way to inspect how it was produced.

Research OS began with a simple question: what if evidence—not just generated text—were the primary output of an AI research workflow?

That led to an evidence-first architecture in which every research run starts from an explicit question and an approved set of sources. A provider selected through the model-agnostic AI registry synthesizes those sources into typed evidence, claims, analysis, verification results, limitations, and a report. The current hackathon configuration uses OpenAI GPT-5.6. Research OS then validates the provenance and stores the complete lineage in one transaction.

The broader inspiration is constitutional computing: governance should define the boundaries of execution without becoming tangled with every implementation detail. In Research OS, the constitutional runtime controls model and token constraints, while modular services, repositories, and adapters handle research operations.

What it does

A user can:

create a research project; connect or import a GitHub repository; preserve repository metadata, README content, Issues, and Pull Requests as research sources; run a governed GPT-5.6 research workflow over approved source material; inspect evidence, claims, analysis, and verification results; view a chronological “show your work” timeline; open the generated Markdown publication; and inspect a SHA-256-backed Research Receipt containing the execution ID, model and workflow versions, entity lineage, warnings, limitations, and report hash.

If GPT-5.6 cites a source outside the approved project source set, Research OS rejects the result and rolls back the entire workflow. No partial or ungrounded research records are committed.

How we built it

The product uses a deliberately layered architecture:

Streamlit for the current user interface; FastAPI for a typed, versioned backend and OpenAPI documentation; Pydantic for transport and structured-output validation; SQLAlchemy 2 with a repository and unit-of-work boundary; SQLite for the hackathon build, with migration-ready database configuration; Alembic for reversible schema migrations; a provider-neutral AI interface and registry, with the OpenAI Responses API and GPT-5.6 as the current hackathon adapter; GitHub App authentication, with a fine-grained local token fallback; JWT-ready API authentication boundaries; GitHub Actions, Ruff, Pytest, and coverage enforcement.

Codex helped transform the initial Streamlit proof of concept and architecture briefs into the backend domain model, API routes, migration system, GitHub integration, governed workflow, adversarial provenance tests, documentation, and CI pipeline. Key decisions—such as using one structured model call per workflow, making the API request the transaction boundary, and describing receipts accurately as hash-backed rather than cryptographically signed—were documented in the repository build log.

Challenges we ran into

Turning an ambitious architecture into working software

The original constitutional-computing vision included many large concepts. The challenge was identifying the smallest implementation that could prove the idea end to end. We focused on a real vertical slice: approved sources become evidence, claims, analysis, verification, a publication, events, and a receipt.

Separating governance from ordinary application logic

A constitutional runtime can easily become a “god object.” We kept it narrow: it authorizes AI workflow execution and enforces model and token constraints. CRUD invariants remain in domain services, while repositories remain persistence-only.

Preventing invented provenance

Typed model output alone does not guarantee grounded research. The workflow therefore validates every returned source ID against the approved project source set. An adversarial automated test makes the model double cite an unauthorized source and verifies that the whole transaction rolls back.

Preserving lineage atomically

Evidence, claims, events, publications, and receipts must agree. Independent commits would leave partial history after a failure. Research OS makes the API request the transaction boundary, so the complete workflow commits together or not at all.

Being precise about trust claims

A SHA-256 report hash is tamper-evident, but it is not a digital signature. A chronological timeline is reconstructable lineage, but it is not guaranteed deterministic replay. We narrowed the product language to match what the implementation genuinely proves.

Making CI portable

The first GitHub Actions run exposed a Linux import-path difference hidden by the local Windows environment. We changed CI to invoke all tools through the selected Python interpreter and upgraded the GitHub Actions runtime versions. The corrected push and pull-request checks both passed.

What’s next

Connect the Streamlit dashboard exclusively through the FastAPI backend. Add a polished Research OS workflow screen with live stage progress and lineage visualization. Deploy a public judge-ready demo with seeded sample research. Connect GitHub imports directly to governed workflow execution. Add URL, document, and academic-paper source adapters. Add human approval checkpoints before publication. Capture immutable prompt versions and complete execution parameters for stronger replay guarantees. Introduce managed signing keys so Research Receipts can become cryptographically signed. Add PostgreSQL, background job execution, rate limits, observability, and production OIDC authentication. Build evaluation suites for citation correctness, claim grounding, verification calibration, and report usefulness.

Why it matters

AI research should not force users to choose between speed and accountability. Research OS demonstrates a practical path toward research that is fast enough to be useful while remaining inspectable, evidence-backed, and honest about its limitations.

Implemented and verified features

Layered FastAPI backend with typed Pydantic schemas and generated OpenAPI documentation. SQLAlchemy 2 domain models, repository/unit-of-work boundaries, SQLite persistence, and a reversible Alembic migration. Project-scoped Source, Evidence, Claim, Analysis, Verification, Publication, Research Event, Research Question, and Research Receipt records. Chronological lineage timeline and atomic request-level transaction handling. Cross-project provenance protection and rollback when AI output cites an unauthorized source. Provider-neutral AIProvider contract, AIResearchRequest, and AIProviderRegistry. Provider and model are explicit workflow inputs and are recorded in publication and receipt lineage. OpenAI Responses API support is isolated in an infrastructure adapter; GPT-5.6 is the Build Week default without being embedded in core workflow services. Modular GitHub REST integration for repository metadata, README content, Issues, and Pull Requests, with GitHub App authentication and a fine-grained-token development fallback. JWT-ready authentication boundary, explicit CORS configuration, workspace confinement, and credential-safe environment configuration. Automated API, provenance, governance, security, GitHub, Mythar, and CHEA conformance tests: 25 tests passing with 93% coverage. GitHub Actions checks passing for the latest CHEA-enabled release-candidate commit. A judge-facing Research OS dashboard with clearly labeled verified sample lineage. A concise README Quick Start covering installation, local execution, demo credentials, and the feature overview. A production-style Docker image verified locally as a non-root container with HTTP 200 and a healthy Streamlit endpoint. A modular Mythar integration using the specified /v2/compile?format=isf contract, strict ISF v0.4 validation, source/evidence persistence, configuration isolation, operator documentation, and automated tests. A CHEA Ω∞ Level 0 reference substrate with typed Execution Envelopes, a replaceable Runtime Adapter contract, deterministic fail-closed Runtime Broker, first-class Broker Selection Records, and Constitutional Execution Records persisted inside Research Receipts. Adversarial CHEA conformance tests verify deterministic selection, capability denial, assurance clamping, resource-limit enforcement, output withholding for INDETERMINATE runs, effective actor identity, and EE → BSR → CER authorization lineage. A project-scoped CER endpoint exposes validated execution records and publishes their schema through FastAPI OpenAPI. A public 2:50 narrated YouTube demonstration covering the problem, dashboard, workflow, evidence, verification, publication, Codex, and GPT-5.6: https://youtu.be/Z1d8Mbwax8w YouTube copyright checks completed with no issues found. MIT license, backend operations guide, GitHub integration guide, and Codex build log.

Current work in progress

The complete judge dashboard, Quick Start, Docker deployment, Mythar integration, and CHEA substrate are published from the accessible fork in upstream PR #3. Its latest CI check passes, but merging remains blocked by the owner-controlled ruleset requiring a nonexistent Main check. The next backend integration connects imported GitHub snapshots through the persistence service and user-triggered API/UI path. The importer and persistence sink exist, but the complete flow is not yet claimed as finished. The public judge deployment is live and verified at https://research-os-judges.streamlit.app. It follows the fork release-candidate branch while upstream merge access is pending.

Planned next milestones

Have the repository owner correct the required status check from Main to test, then review and merge PR #3. Complete backend persistence integration for GitHub imports. Add request and response examples to every OpenAPI endpoint. Implement role-based authentication and authorization. Add durable background jobs for scheduled and on-demand GitHub synchronization. Extend the verified single-container judge deployment into a full backend and local-dependency Docker Compose stack. Promote the verified judge deployment from the fork branch to the upstream v0.1.0 release after PR #3 merges. Route the Streamlit interface entirely through FastAPI and add visible workflow-stage progress. Add URL, document, and academic-paper source adapters. Add human approval checkpoints, evaluation suites, observability, PostgreSQL, managed CER/receipt signing, isolated-sandbox adapters, and hardware or multi-party attestation for higher CHEA assurance levels.

These sections distinguish verified code from active work and future plans so the submission remains accurate for judges.

Built With

• artifacts
• automated
• checks
• ci/cd
• conformance
• console
• constitutional
• dashboard
• data
• devops
• evidence
• frontend
• next.js
• os
• pipelines
• postgresql
• react
• research
• security
• server
• sqlite
• storage
• tooling
• verification
• workflow