Nobra Calculator 🏥

Modular API for medical calculations and scores developed with FastAPI, originally designed for Nobra, our AI research agent for medical doctors.

🌐 Live API

🚀 Try it now at: https://calculator.nobra.app.br/docs

• Free tier: 10 requests per second
• Commercial use: Contact us at daniel@nobregamedtech.com.br for higher limits
• Self-hosted: Deploy locally using the instructions below

📋 Description

Nobra Calculator is a scalable REST API that allows the calculation of various medical scores and indices. Originally developed as part of the Nobra ecosystem at Nobrega MedTech, we've decided to open-source this powerful tool to benefit the global medical community.

Our company specializes in AI solutions for healthcare, focusing on academic support and medical decision-making tools. This calculator represents our commitment to advancing evidence-based medicine through technology.

Features

• Modular: Specialty-organized structure for easy addition of new medical scores
• Scalable: Clean architecture designed for growth
• Documented: Automatic documentation with Swagger/OpenAPI
• Validated: Robust parameter validation with Pydantic
• Interpreted: Returns not only the result but also the clinical interpretation

🚀 Quick Start

Prerequisites

• Python 3.8+
• pip

Installation

1. Clone the repository:

git clone https://github.com/danielxmed/nobra_calculator.git
cd nobra_calculator

2. Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Run the API:

python main.py

The API will be available at http://localhost:8000

📖 Documentation

Live API Documentation

• Swagger UI: https://calculator.nobra.app.br/docs
• ReDoc: https://calculator.nobra.app.br/redoc
• Health Check: https://calculator.nobra.app.br/health

Local Development Documentation

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• Health Check: http://localhost:8000/health

🛠️ API Endpoints

Scores

• GET /api/scores - Lists all available scores
• GET /api/scores/{score_id} - Metadata for a specific score
• GET /api/categories - Lists medical categories
• POST /api/reload - Reloads scores and calculators

Specific Score Endpoints

Each score also has its dedicated endpoint:

• POST /ckd_epi_2021 - CKD-EPI 2021
• POST /cha2ds2_vasc - CHA₂DS₂-VASc ...

System

• GET /health - API health check
• GET / - API information

📁 Project Structure

nobra_calculator/
├── app/
│   ├── models/
│   │   ├── shared.py           # Common models and enums
│   │   └── scores/             # Score models by specialty
│   │       ├── cardiology/
│   │       ├── nephrology/
│   │       ├── pulmonology/
│   │       └── ...
│   ├── routers/
│   │   ├── scores.py           # Main router with common endpoints
│   │   └── scores/             # Score endpoints by specialty
│   │       ├── cardiology/
│   │       ├── nephrology/
│   │       └── ...
│   └── services/               # Business Logic
├── calculators/                # Calculation Modules
├── scores/                     # Score Metadata (JSON)
├── main.py                     # Main application
└── requirements.txt            # Dependencies

🔧 Adding New Scores

To add a new score:

1. Create the JSON metadata file

Create /scores/{score_id}.json with the score metadata:

{
  "id": "new_score",
  "title": "Score Title",
  "description": "Detailed description",
  "category": "medical_specialty",
  "parameters": [...],
  "result": {...},
  "interpretation": {...}
}

2. Create the calculation module

Create /calculators/{score_id}.py:

def calculate_new_score(param1, param2):
    # Calculation logic
    result = ...
    return {
        "result": result,
        "unit": "unit",
        "interpretation": "interpretation"
    }

3. Create the Pydantic models

Create /app/models/scores/{specialty}/{score_id}.py:

from pydantic import BaseModel, Field

class NewScoreRequest(BaseModel):
    """Request model for New Score"""
    param1: str = Field(..., description="Parameter 1")
    param2: float = Field(..., description="Parameter 2")

class NewScoreResponse(BaseModel):
    """Response model for New Score"""
    result: float = Field(..., description="Calculation result")
    unit: str = Field(..., description="Result unit")
    interpretation: str = Field(..., description="Clinical interpretation")

4. Create the router endpoint

Create /app/routers/scores/{specialty}/{score_id}.py:

from fastapi import APIRouter, HTTPException
from app.models.scores.{specialty}.{score_id} import NewScoreRequest, NewScoreResponse
from app.services.calculator_service import calculator_service

router = APIRouter()

@router.post("/new_score", response_model=NewScoreResponse)
async def calculate_new_score(request: NewScoreRequest):
    """Calculate New Score"""
    try:
        result = calculator_service.calculate_score("new_score", request.dict())
        return NewScoreResponse(**result)
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

5. Update the specialty init.py files

• Add imports to /app/models/scores/{specialty}/__init__.py
• Add router to /app/routers/scores/{specialty}/__init__.py

6. Reload the scores

curl -X POST http://localhost:8000/api/reload

🧪 Testing

Manual test with curl:

# Health check
curl http://localhost:8000/health

# List scores
curl http://localhost:8000/api/scores

# Calculate CKD-EPI 2021 (Live API)
curl -X POST https://calculator.nobra.app.br/ckd_epi_2021 \
  -H "Content-Type: application/json" \
  -d '{"sex": "female", "age": 65, "serum_creatinine": 1.2}'

# Calculate CKD-EPI 2021 (Local)
curl -X POST http://localhost:8000/ckd_epi_2021 \
  -H "Content-Type: application/json" \
  -d '{"sex": "female", "age": 65, "serum_creatinine": 1.2}'

🤝 Contributing

We welcome contributions from the medical and developer communities! This project is part of our mission to democratize access to evidence-based medical tools.

How to Contribute

1. Fork the project on GitHub
2. Create a feature branch (git checkout -b feature/amazing-new-score)
3. Add your medical calculator following our implementation guide
4. Test thoroughly - medical calculations require precision
5. Include proper references - all scores must cite original publications
6. Commit your changes (git commit -am 'Add APACHE II score')
7. Push to your branch (git push origin feature/amazing-new-score)
8. Open a Pull Request with a detailed description

What We're Looking For

• New medical scores and calculators from any medical specialty
• Bug fixes and improvements to existing calculations
• Documentation enhancements and translations
• Performance optimizations and code quality improvements
• Test coverage improvements

Code Quality Standards

• Follow our established patterns for new calculators
• Include comprehensive input validation
• Provide clinical interpretations for all results
• Cite original research using Vancouver style references
• Test with edge cases and boundary values

📄 License

This project is licensed under Apache 2.0. See the LICENSE file for details.

👨‍💻 About

Author

Daniel Nobrega Medeiros

• Email: daniel@nobregamedtech.com.br
• GitHub: @danielxmed
• Repository: https://github.com/danielxmed/nobra_calculator.git

Company

Nobrega MedTech - AI Solutions for Healthcare

• Specializing in academic support tools for medical education
• Developing AI-powered medical decision support systems
• Building the Nobra ecosystem - AI research agents for medical professionals
• Committed to evidence-based medicine and open-source healthcare tools

The Nobra Project

This calculator was originally developed as a component of Nobra, our comprehensive AI research agent designed to assist medical doctors with:

• Evidence-based clinical decision making
• Medical literature research and synthesis
• Educational support for medical training
• Real-time access to medical calculators and scores

By open-sourcing this calculator API, we're contributing to the global effort to make medical knowledge more accessible and standardized.

🌟 Support the Project

• ⭐ Star this repository if you find it useful
• 🐛 Report bugs and suggest improvements
• 📖 Contribute new calculators from your medical specialty
• 📢 Share with colleagues in the medical community
• 💼 Contact us for enterprise solutions and custom development

🔌 MCP (Model Context Protocol) Integration

About MCP

The Nobra Calculator API includes built-in MCP server support, allowing AI assistants and other MCP-compatible clients to interact with all medical calculators as native tools.

Connecting to MCP

• MCP Endpoint: https://calculator.nobra.app.br/mcp
• Protocol: Connect via URL using the MCP client of your choice
• Authentication: Same as the main API (rate limits apply)

Important Considerations

⚠️ WARNING: The MCP server exposes over 300 medical calculator tools. When connecting:

• Select specific tools you need in your MCP client interface
• Avoid loading all tools at once - this will exceed most LLM context windows
• Use tool filtering to choose only the medical specialties or specific calculators relevant to your use case

Example Tool Categories

• Cardiology scores (CHA2DS2-VASc, HAS-BLED, etc.)
• Nephrology calculators (CKD-EPI, MDRD, etc.)