research-tool-cli 0.1.0__tar.gz

research_tool_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manjunath N K
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

research_tool_cli-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: research-tool-cli
+Version: 0.1.0
+Summary: Retrospective clinical research tool with outcome-masking and provenance
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: pandas>=2.0
+Requires-Dist: scipy>=1.11
+Requires-Dist: statsmodels>=0.14
+Requires-Dist: lifelines>=0.27
+Requires-Dist: tableone>=0.8
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: fastapi>=0.141.1
+Requires-Dist: uvicorn>=0.52.0
+Dynamic: license-file

research_tool_cli-0.1.0/README.md

@@ -0,0 +1,101 @@
+# Retrospective Clinical Research Tool
+
+Local-first CLI and Web application that takes raw retrospective clinical study data to a STROBE-compliant manuscript draft. Built around a provenance-first, outcome-masking workflow to prevent HARKing and p-hacking.
+
+## Setup
+
+```bash
+pip install -e .
+```
+
+For development and tests, install the project environment with its dev dependencies and run pytest through that interpreter:
+
+```bash
+uv sync --dev
+.venv/bin/python -m pytest
+```
+
+This keeps pytest on the same Python environment as scipy, pandas, and tableone.
+
+## Usage (CLI)
+
+```bash
+# ── Phase 1: Pre-Unmasking Protocol Specification ──────────────────────────
+# 1. Create study
+research-tool new-study "EMD Study"
+
+# 2. Ingest CSV data
+research-tool ingest <STUDY_ID> /Users/manjunathnk/Research/research-tool/synthetic_21_v2.csv
+
+# 3. Classify variables (masks outcome variables)
+research-tool classify-variables <STUDY_ID>
+
+# 4. Explore baseline data (outcomes masked)
+research-tool explore-baseline <STUDY_ID>
+
+# 5. Declare study plan
+research-tool plan <STUDY_ID> --type cohort --comparison "PFS by treatment arm" --outcome-var-ids "8,9" --test "8:kaplan_meier_logrank:KM PFS comparison" --cox-ph-models "pfs_multivariable:pfs_days:pfs_event:treatment_arm:age,high_risk_fish,prior_lines:Adjusted PFS model"
+
+# 6. Lock study plan
+research-tool lock <STUDY_ID>
+
+# ── Phase 2: Data Unmasking & Execution ──────────────────────────────────
+# 7. Unmask outcome data
+research-tool unmask <STUDY_ID>
+
+# 8. Run analyses
+research-tool analyze <STUDY_ID> --force
+
+# ── Phase 3: Visualizations & Tables ──────────────────────────────────────
+# 9. Table 1 (baseline characteristics)
+research-tool table1 <STUDY_ID>
+
+# 10. Kaplan-Meier plot (requires test_id, e.g. 1)
+research-tool plot-km <STUDY_ID> 1
+
+# 11. Forest plot (SVG & ASCII)
+research-tool plot-forest <STUDY_ID>
+research-tool plot-forest <STUDY_ID> --ascii
+
+# 12. CONSORT flowchart
+research-tool flowchart <STUDY_ID>
+
+# ── Phase 4: Compliance & Reporting ───────────────────────────────────────
+# 13. STROBE checklist audit
+research-tool strobe-check <STUDY_ID>
+
+# 14. Manuscript draft
+research-tool draft <STUDY_ID>
+
+# 15. Provenance lineage DAG
+research-tool lineage <STUDY_ID>
+
+# 16. Data forensics
+research-tool forensics <STUDY_ID>
+
+# 17. Reviewer JSON export
+research-tool export <STUDY_ID>
+
+# ── Phase 5: Bundling, Excel Export & Verification ───────────────────────
+# 18. Create hash-verified bundle archive (generates manifest & composite SHA-256)
+research-tool bundle <STUDY_ID>
+
+# 19. Export Excel report (reads bundle manifest & populates composite hash on Tab 4)
+research-tool export-excel <STUDY_ID>
+
+# 20. Verify bundle integrity
+research-tool verify-bundle data/studies/<STUDY_ID>/<STUDY_ID>_bundle.tar.gz
+```
+
+> **Note:** Variable IDs are auto-assigned per-study at ingest time and are **not predictable**. Always run `list-variables` after `classify-variables` to get the correct IDs for `--outcome-var-ids`.
+
+See `research-tool --help` and `app/README.md` for web interface instructions.
+
+---
+
+## Authors & Acknowledgments
+
+- **Lead Maintainer**: [Manjunath N K](https://github.com/nkmanjunath)
+- **AI Pair Programming & Collaboration**:
+  - **Google Antigravity (AGY)** — Pair Programming, 4-Gate Diagnostics & UI/UX design.
+  - **OpenCode** — Statistical engine verification & benchmarking fixtures.

research_tool_cli-0.1.0/app/backend/_bootstrap.py

@@ -0,0 +1,15 @@
+"""
+Backend bootstrap module.
+Ensures repository root and backend directory are registered in sys.path.
+Exposes BACKEND_DIR and REPO_ROOT paths.
+"""
+from pathlib import Path
+import sys
+
+BACKEND_DIR = Path(__file__).resolve().parent
+REPO_ROOT = BACKEND_DIR.parent.parent
+
+if str(REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(REPO_ROOT))
+if str(BACKEND_DIR) not in sys.path:
+    sys.path.insert(0, str(BACKEND_DIR))

research_tool_cli-0.1.0/app/backend/exports/verification_script.py

@@ -0,0 +1,19 @@
+"""
+Standalone audit-binder verification script.
+Checks (per DECISIONS.md §7.2):
+  1. Hash-chain integrity: H0 -> H1[-> Hn] -> Hexec unbroken.
+  2. Protocol audit: no post-hoc parameter changes between lock and execution.
+  3. Deterministic re-fit within a relative tolerance of ~1e-4.
+"""
+import json, hashlib, sys
+
+def check_chain(manifest):
+    print("Checking hash chain...")
+    print(f"  H0     = {manifest['h0']}")
+    print(f"  H1..Hn = {manifest['plan_chain']}")
+    print(f"  Hexec  = {manifest['hexec']}")
+
+if __name__ == "__main__":
+    with open("manifest.json") as f:
+        m = json.load(f)
+    check_chain(m)

research_tool_cli-0.1.0/app/backend/main.py

@@ -0,0 +1,59 @@
+"""
+Sandbox-to-Vault app — FastAPI backend.
+localhost only. Phase 1 = Tab 1, Tab 2, Tab 3, & Tab 4 wired live.
+"""
+from _bootstrap import BACKEND_DIR, REPO_ROOT  # noqa: F401
+
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+from fastapi.middleware.cors import CORSMiddleware
+
+from routers import ingestion, planning, execution, reporting
+
+tags_metadata = [
+    {
+        "name": "Ingestion (Tab 1)",
+        "description": "Blinded dataset upload, schema mapping, sentinel configuration, and Stage 1 (H0) protocol vaulting.",
+    },
+    {
+        "name": "Planning (Tab 2)",
+        "description": "Socratic Wizard for pre-registering exposure, confounders, missing-data strategy, live EPV calculations, and Stage 2 (H1) protocol lock.",
+    },
+    {
+        "name": "Execution (Tab 3)",
+        "description": "Unattended statistical execution (Logistic / Cox PH), 4 diagnostic gates (Separation, VIF, Proportional Hazards, Linearity), and Autopsy Canvas remediation routing.",
+    },
+    {
+        "name": "Reporting (Tab 4)",
+        "description": "Journal-ready manuscript assets (Table 1 Baseline Balance with SMD, Table 2 Primary Effect Estimates, Interactive SVG Forest Plots, STROBE Checklists, Cryptographic Audit Binder).",
+    },
+]
+
+app = FastAPI(
+    title="Clinical Research Tool — Sandbox-to-Vault Engine",
+    description="Publication-grade, audit-sealed epidemiological and clinical trial analytical framework.",
+    version="1.2.0-strobe-default",
+    openapi_tags=tags_metadata,
+)
+
+# CORS middleware for local SPA
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["http://localhost:5173", "http://127.0.0.1:5173", "http://localhost:8000"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(ingestion.router, prefix="/api/ingest", tags=["Ingestion (Tab 1)"])
+app.include_router(planning.router, prefix="/api/plan", tags=["Planning (Tab 2)"])
+app.include_router(execution.router, prefix="/api/execute", tags=["Execution (Tab 3)"])
+app.include_router(reporting.router, prefix="/api/report", tags=["Reporting (Tab 4)"])
+
+# Serve exports directory for HTML/SVG asset viewing
+exports_dir = REPO_ROOT / "exports"
+exports_dir.mkdir(exist_ok=True)
+app.mount("/exports", StaticFiles(directory=str(exports_dir)), name="exports")
+
+# Serve the vanilla JS SPA
+frontend_dir = BACKEND_DIR.parent / "frontend"
+app.mount("/", StaticFiles(directory=str(frontend_dir), html=True), name="frontend")

research_tool_cli-0.1.0/app/backend/routers/__init__.py

@@ -0,0 +1 @@
+"""Routers package for research-tool backend API."""