coregrai 2.1.1
AI-powered study assistant for the ACR Core Exam and diagnostic radiology
Requires Python: >=3.8
Keywords: radiology, medical, education, ACR, exam, study, AI, differential-diagnosis

# GRAi CLI

> AI-powered study assistant for the ACR Core Exam and diagnostic radiology

[![PyPI version](https://badge.fury.io/py/grai-cli.svg)](https://badge.fury.io/py/grai-cli)
[![Python Versions](https://img.shields.io/pypi/pyversions/grai-cli.svg)](https://pypi.org/project/grai-cli/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 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)

```bash
pip install grai-cli
```

### From Source

```bash
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

```bash
grai login
```

You'll be prompted for your email and password. Don't have an account? Register at https://coregrai.com

### 2. Ask Questions

```bash
# Single question
grai chat "What are the CT findings in pulmonary embolism?"

# Interactive chat session
grai chat -i
```

### 3. Take a Quiz

```bash
# 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

```bash
# 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

```bash
grai stats
```

## Usage Guide

### Chat Commands

**Single Query:**
```bash
grai chat "Explain MRI sequences"
```

**Interactive Mode:**
```bash
grai chat -i
```

**With Sources:**
```bash
grai chat --sources "What is the ACR TI-RADS classification?"
```

**Specify Model:**
```bash
grai chat --model gemini "Describe CT protocols"
```

### Quiz Commands

**Basic Quiz:**
```bash
grai quiz
```

**Topic-Specific:**
```bash
# 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:**
```bash
grai quiz --difficulty hard --count 10
```

**Adaptive Mode:**
```bash
# Questions adjust based on your performance
grai quiz --adaptive
```

### Lesson Commands

**List Lessons:**
```bash
grai lesson --list
```

**Search Lessons:**
```bash
grai lesson --search "mri"
grai lesson --search "cardiac" --category cardiothoracic
```

**Read a Lesson:**
```bash
grai lesson chest-radiography-basics
```

**Export Lesson:**
```bash
grai export chest-radiography-basics --output ~/study/chest.md
```

### Configuration

**Show Current Config:**
```bash
grai config --show
```

**Change Server URL:**
```bash
grai config --server https://your-server.com
```

**View Statistics:**
```bash
grai stats
```

**Logout:**
```bash
grai logout
```

## Advanced Usage

### Custom Server

If you're running your own GRAi instance:

```bash
grai config --server http://localhost:5000
grai login
```

### Batch Operations

Study multiple topics in sequence:

```bash
# 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:

```bash
#!/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`:

```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

```bash
# Check server connectivity
curl https://coregrai.com/api/health

# Try alternative server
grai config --server https://backup.coregrai.com
```

### Authentication Problems

```bash
# Re-login
grai logout
grai login
```

### Clear Configuration

```bash
# Remove config file
rm ~/.grai/config.json

# Login again
grai login
```

## Development

### Setup Development Environment

```bash
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

```bash
pytest
pytest --cov=grai_cli
```

### Code Formatting

```bash
black grai_cli/
flake8 grai_cli/
```

### Build Package

```bash
python -m build
twine check dist/*
```

### Publish to PyPI

```bash
# 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](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](CHANGELOG.md) for a list of changes.

## Acknowledgments

- Built with [Click](https://click.palletsprojects.com/)
- Beautiful terminal output powered by [Rich](https://rich.readthedocs.io/)
- ACR content based on official ACR guidelines and appropriateness criteria

---

**Made with ❤️ for radiology residents everywhere**