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.)
• Pulmonology tools (CURB-65, PSI, etc.)
• Emergency medicine scores
• And many more across 15+ medical specialties

MCP Client Configuration

When configuring your MCP client, consider:

1. Setting up tool filters by specialty or score name
2. Implementing pagination or lazy loading for tool discovery
3. Caching frequently used calculator tools
4. Managing context window usage efficiently

For more information about MCP integration, refer to the MCP documentation.

⚠️ Medical Disclaimer

IMPORTANT: This API is intended for educational and research purposes only. It should not be used as a substitute for professional clinical judgment. All medical calculations should be verified independently, and clinical decisions should always involve qualified healthcare professionals.

• Always validate results with original references
• Consider patient-specific factors not captured in scores
• Use as a supplement to, not replacement for, clinical expertise
• Verify calculations independently for critical decisions