Skip to content

DEV Community

Tarek Mohamed

Posted on Oct 31

Building MedOrqis: An Open-Source Medical AI Skills Ecosystem for Safe Clinical Agents

#mlhacks #devchallenge #hackathon #ai

This is a submission for the MLH x DEV Writing Challenge

seotarek / MedOrqis

MedOrqis — Medical AI Skills Ecosystem: 24 Specialized Clinical AI Skills, Deterministic Safety Guardrails & Zero-Token Calculators

MedOrqis — Medical AI Skills Ecosystem (v2.1.1)

MedOrqis is an open-source, evidence-grounded, cross-platform ecosystem of 24 specialized clinical AI skills, 12 deterministic zero-token clinical calculators & safety engines, and multi-platform adapters (Skills CLI, Claude Code, Gemini CLI, Model Context Protocol, and OpenAI).

Tip

🌐 Interactive Web Hub & Live Zero-Token Calculators:
Explore the live searchable 24-skill catalog, test interactive clinical calculators (ESC 2024 CHA₂DS₂-VA, CKD-EPI 2021, Bedside Schwartz, HAS-BLED, NEWS2, DDI Checker), and inspect dialect benchmarks directly in your browser at https://seotarek.github.io/MedOrqis/.

⚡ Fleet Install in 1-Second (Claude Code, Cursor, Codex, Antigravity, OpenCode):

npx skills add seotarek/MedOrqis

Built with an evidence-first, patient-safety-first architecture, MedOrqis eliminates medical hallucination risks in high-stakes clinical calculations by executing arithmetic, unit conversions, PHI scrubbing, negation parsing, and drug interaction screenings through a local, deterministic Python core with zero LLM API token overhead.

⚡ 1-Minute Quick Start & Integration

…

What I Built

Deploying Large Language Models in healthcare and clinical decision support presents a terrifying paradox: while AI models excel at synthesizing complex medical literature, they remain notoriously unreliable at basic arithmetic, dosage calculations, and hard rule enforcement. In clinical medicine, a misplaced decimal point or a hallucinated contraindication can be fatal.

To solve this foundational safety gap, I built MedOrqis: a modular, cross-platform, open-source ecosystem of 24 specialized clinical AI skills, deterministic safety guardrails, and zero-token clinical calculation engines.

The Core Architectural Pillars:

Zero-Token Clinical Engines: Critical medical equations (such as CKD-EPI 2021 eGFR, CHA2DS2-VA 2024 ESC, Cockcroft-Gault CrCl, Wells DVT/PE scores, and CURB-65) are computed deterministically in pure Python/C. They never rely on LLM token generation, guaranteeing 100% mathematical precision and zero hallucination.
Epistemic Context Provenance: Introduces the ClinicalContextEnvelope schema, which tags every datum with its exact epistemic origin (USER_REPORTED_UNVERIFIED, DOCUMENTED_CLINICAL_RECORD, DETERMINISTIC_CALCULATION, or MODEL_INFERRED_HYPOTHESIS). High-risk dosing skills strictly reject unverified hypotheses as confirmed indications.
Cross-Platform Agent Adapters: MedOrqis is designed to run everywhere — as Claude Agent Skills (SKILL.md), Gemini CLI Extensions, OpenAI Strict Structured Tooling, and a standalone Model Context Protocol (MCP) server.
Multilingual Clinical Invariance: Specifically calibrated to preserve clinical negation polarity and numeric BiDi integrity across English, Modern Standard Arabic (MSA), and regional clinical vernaculars.

Demo

Here is how MedOrqis executes deterministic clinical equations and safety guardrails without wasting LLM tokens or risking calculation drift:

1. Deterministic Renal Function (CKD-EPI 2021 Race-Free Equation)

from medorqis.calculators import ckd_epi_2021_egfr

# Computes exact eGFR using official Inker et al. (NEJM 2021) race-free standards
result = ckd_epi_2021_egfr(
    serum_creatinine_mg_dl=1.45,
    age_years=64,
    is_female=True
)

print(f"Calculated eGFR: {result.score} {result.unit}")
print(f"Staging: {result.interpretation_band}")
print(f"Guideline Source: {result.guideline_citation} ({result.guideline_year})")
# Output:
# Calculated eGFR: 42.8 mL/min/1.73m2
# Staging: G3b - Moderate to Severe Reduction
# Guideline Source: Inker et al., NEJM 2021 (2021)

2. Guardrails & Provenance Verification

from medorqis.guardrails import ContextProvenanceGuard, ProvenanceType

guard = ContextProvenanceGuard()

# Flagging an unverified user statement
user_claim = {
    "drug": "Apixaban",
    "provenance": ProvenanceType.USER_REPORTED_UNVERIFIED
}

# The guardrail blocks automated high-risk interaction dosing without clinical documentation
is_valid, reason = guard.verify_for_dosing(user_claim)
if not is_valid:
    print(f"Safety Gate Enforced: {reason}")
    # Enforces clinician review before dangerous dosage modulation

Partner Technologies

To bring MedOrqis from an abstract concept to a production-grade clinical engineering framework, I leveraged cutting-edge developer platforms:

Model Context Protocol (MCP): Implemented an audited, high-throughput MCP server (mcp_server/medorqis_mcp_server.py) over stdio and SSE. This enables AI assistants like Claude Desktop, Cursor, and Antigravity to invoke MedOrqis clinical tools with strictly typed JSON schemas.
GitHub & GitHub Actions CI/CD: Built automated verification workflows that test every clinical calculation against peer-reviewed validation fixtures, ensuring zero code drift on pull requests.
Python Standard Library First-Principles: Core calculators are implemented using Python's native math, decimal, and dataclasses modules, allowing MedOrqis to run in ultra-lightweight, sandboxed microservices with zero heavy external dependencies.

Hackathon Experience

Building MedOrqis during this hackathon sprint was an exhilarating deep dive at the intersection of medicine and software architecture.

The most challenging — and rewarding — phase was designing the Epistemic Provenance Envelope. In standard LLM chats, models treat a patient saying "I think my uncle gave me some blue pills" with the same evidentiary weight as a verified laboratory blood panel. Forcing the agentic pipeline to explicitly classify and gate data provenance required rethinking how AI agents interact with clinical workflows.

This project proved that the future of Medical AI does not lie in building bigger, opaque black-box models. It lies in hybrid architectures: pairing the linguistic reasoning of LLMs with transparent, deterministic, verifiable code that doctors, pharmacists, and patients can trust unconditionally.

GitHub Repository: https://github.com/seotarek/MedOrqis

Star the repository on GitHub and let me know your thoughts on deterministic medical AI in the comments below!

Top comments (0)

Subscribe