GRAi CLI

DEPRECATED -- this package is no longer maintained. Some commands no longer work against the current CoreGRAi service. Use the web app instead: https://coregrai.com

AI-powered study assistant for the ACR Core Exam and diagnostic radiology

Overview

GRAi CLI brings the power of AI-assisted radiology education to your terminal. Study for the ACR Core Exam with interactive chat, practice quizzes, and comprehensive lessons - all from the command line.

Features

• Interactive Chat: Ask questions about any radiology topic and get AI-powered explanations
• Practice Quizzes: Board-style questions with adaptive difficulty
• Comprehensive Lessons: 572+ pre-generated lessons covering all ACR topics
• Progress Tracking: Monitor your study statistics and performance
• Offline Export: Save lessons to markdown files for offline study
• Beautiful Terminal UI: Rich, colorful interface with syntax highlighting

Installation

From PyPI (Recommended)

pip install grai-cli

From Source

git clone https://github.com/yourusername/grai-cli.git
cd grai-cli
pip install -e .

Requirements

• Python 3.8 or higher
• Active internet connection (for API access)
• GRAi account (free registration at https://coregrai.com)

Quick Start

1. Login

grai login

You'll be prompted for your email and password. Don't have an account? Register at https://coregrai.com

2. Ask Questions

# Single question
grai chat "What are the CT findings in pulmonary embolism?"

# Interactive chat session
grai chat -i

3. Take a Quiz

# Random quiz (5 questions)
grai quiz

# Topic-specific quiz
grai quiz --topic chest-ct --count 10

# Adaptive difficulty based on your performance
grai quiz --adaptive

4. Study Lessons

# List all available lessons
grai lesson --list

# Search for lessons
grai lesson --search "cardiac"

# Read a specific lesson
grai lesson chest-radiography-basics

5. Check Your Progress

grai stats

Usage Guide

Chat Commands

Single Query:

grai chat "Explain MRI sequences"

Interactive Mode:

grai chat -i

With Sources:

grai chat --sources "What is the ACR TI-RADS classification?"

Specify Model:

grai chat --model gemini "Describe CT protocols"

Quiz Commands

Basic Quiz:

grai quiz

Topic-Specific:

# Available topics: chest-xray, chest-ct, neuro-ct, neuro-mri,
# abdominal-ct, abdominal-mri, msk, nuclear-medicine, ultrasound, etc.
grai quiz --topic neuro-mri

Set Difficulty:

grai quiz --difficulty hard --count 10

Adaptive Mode:

# Questions adjust based on your performance
grai quiz --adaptive

Lesson Commands

List Lessons:

grai lesson --list

Search Lessons:

grai lesson --search "mri"
grai lesson --search "cardiac" --category cardiothoracic

Read a Lesson:

grai lesson chest-radiography-basics

Export Lesson:

grai export chest-radiography-basics --output ~/study/chest.md

Configuration

Show Current Config:

grai config --show

Change Server URL:

grai config --server https://your-server.com

View Statistics:

grai stats

Logout:

grai logout

Advanced Usage

Custom Server

If you're running your own GRAi instance:

grai config --server http://localhost:5000
grai login

Batch Operations

Study multiple topics in sequence:

# Create a study script
#!/bin/bash
grai quiz --topic chest-ct --count 5
grai quiz --topic chest-xray --count 5
grai quiz --topic neuro-ct --count 5
grai stats

Export Study Materials

Export all cardiothoracic lessons:

#!/bin/bash
for lesson in $(grai lesson --list --category cardiothoracic | grep -oP '^\S+'); do
    grai export "$lesson" --output "study/${lesson}.md"
done

Configuration File

GRAi CLI stores configuration in ~/.grai/config.json:

{
  "server_url": "https://coregrai.com",
  "default_model": "deepseek",
  "show_sources": false,
  "color_output": true,
  "auth_token": "<your-token>",
  "user_email": "your@email.com"
}

Features in Detail

Interactive Chat

The interactive chat mode provides a conversational interface:

> You: What causes pneumothorax on chest x-ray?

GRAi: Pneumothorax appears on chest radiographs as...
[detailed explanation with key findings]

Sources:
  1. Chest Radiography Fundamentals
  2. Emergency Radiology - Pneumothorax
  3. ACR Appropriateness Criteria

> You: How do you measure it?
...

Practice Quizzes

Board-style questions with immediate feedback:

Question 1/10:
A 45-year-old male presents with chest pain...
Which finding is most concerning?

  1. Cardiomegaly
  2. Pleural effusion
  3. Pneumomediastinum
  4. Atelectasis

Your answer: 3

Correct! Pneumomediastinum in the setting of chest pain
may indicate esophageal perforation, which requires urgent
evaluation.

Progress Tracking

Monitor your improvement:

Your Study Statistics
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Questions Answered    847
Lessons Completed     42
Study Streak          14 days
Average Score         84.5%
Total Study Time      23h 15m

Areas to Focus On:
  - Nuclear Medicine Physics
  - Interventional Radiology
  - Ultrasound Artifacts

Troubleshooting

Connection Issues

# Check server connectivity
curl https://coregrai.com/api/health

# Try alternative server
grai config --server https://backup.coregrai.com

Authentication Problems

# Re-login
grai logout
grai login

Clear Configuration

# Remove config file
rm ~/.grai/config.json

# Login again
grai login

Development

Setup Development Environment

git clone https://github.com/yourusername/grai-cli.git
cd grai-cli
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements-dev.txt
pip install -e .

Run Tests

pytest
pytest --cov=grai_cli

Code Formatting

black grai_cli/
flake8 grai_cli/

Build Package

python -m build
twine check dist/*

Publish to PyPI

# Test PyPI
twine upload --repository testpypi dist/*

# Production PyPI
twine upload dist/*

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Documentation: https://docs.coregrai.com
• Issues: https://github.com/yourusername/grai-cli/issues
• Email: support@coregrai.com

Changelog

See CHANGELOG.md for a list of changes.

Acknowledgments

• Built with Click
• Beautiful terminal output powered by Rich
• ACR content based on official ACR guidelines and appropriateness criteria

---

Made with ❤️ for radiology residents everywhere