epump-inspector 1.0.0

ePump Inspector Library and CLI for Firestore database analysis

Database Inspector Tool

A Python-based inspector tool for querying and analyzing ePump.app's Firestore database.

Features

• Database Abstraction: Easy to switch between different database backends
• AI Analysis Queries: Retrieve AI training and analysis data
• AI Feedback Queries: Access user feedback on AI interactions
• Workout Data: Query workout sessions and exercise data
• User Data: Retrieve user information
• Generic Collections: Query any Firestore collection path
• JSON Output: All results in JSON format for easy processing

Installation

Option 1: Using Poetry (Recommended)

cd tool

# Install Poetry if you haven't already
curl -sSL https://install.python-poetry.org | python3 -

# Install dependencies and create virtual environment
poetry install

# Activate the virtual environment
poetry shell

# Or run commands directly with poetry
poetry run epump-inspector --help

Option 2: Using pip (Legacy)

cd tool
pip install -r requirements.txt

Configuration

Option 1: Environment File (.env) - Recommended

# Copy the example file
cp .env.example .env

# Edit .env with your actual values
FIREBASE_PROJECT_ID=your-project-id
FIREBASE_CREDENTIALS=/path/to/your/service-account.json
DEFAULT_LIMIT=10

Option 2: Environment Variables

export FIREBASE_PROJECT_ID="your-project-id"
export FIREBASE_CREDENTIALS="/path/to/service-account.json"

Option 3: Command-Line Arguments

python inspector.py --project-id your-project-id --credentials /path/to/service-account.json COMMAND

Note: The tool will load configuration in this priority order:

1. Command-line arguments (highest priority)
2. Environment variables
3. .env file values (lowest priority)

Usage

Get AI Analysis Data

# Using Poetry
poetry run epump-inspector ai-analysis
poetry run epump-inspector ai-analysis --user-id USER_ID --limit 20 --pretty

# Using direct Python (if not using Poetry)
python inspector.py ai-analysis
python inspector.py ai-analysis --user-id USER_ID --limit 20 --pretty

# If you're in the Poetry shell
epump-inspector ai-analysis --pretty

Get AI Feedback

# Using Poetry
poetry run epump-inspector ai-feedback
poetry run epump-inspector ai-feedback --user-id USER_ID --limit 50

# Using direct Python
python inspector.py ai-feedback --user-id USER_ID --limit 50

Get Workout Data

# Using Poetry
poetry run epump-inspector workouts
poetry run epump-inspector workouts --user-id USER_ID

# Using direct Python
python inspector.py workouts --user-id USER_ID

Get User Data

# Using Poetry
poetry run epump-inspector users --limit 5

# Using direct Python
python inspector.py users --limit 5

Query Generic Collections

# Using Poetry
poetry run epump-inspector collection --path users
poetry run epump-inspector collection --path users/USER_ID/supplements --pretty

# Using direct Python
python inspector.py collection --path users/USER_ID/ai_feedback --pretty

Output Format

All commands output JSON with the following structure:

{
  "command": "ai-analysis",
  "count": 10,
  "user_id": "optional_user_id",
  "data": [
    {
      "_id": "document_id",
      "field1": "value1",
      "field2": "value2"
    }
  ]
}

Database Abstraction

The tool uses a DAO (Data Access Object) pattern for database abstraction:

• DatabaseDAO: Abstract base class defining the interface
• FirestoreDAO: Firestore implementation

To add a new database backend:

1. Create a new class inheriting from DatabaseDAO
2. Implement all abstract methods
3. Update inspector.py to use the new DAO

Available Methods in DAO

• connect(**kwargs): Connect to database
• disconnect(): Disconnect from database
• get_ai_analysis(user_id, limit): Get AI analysis data
• get_ai_feedback(user_id, limit): Get AI feedback data
• get_workouts(user_id, limit): Get workout data
• get_users(limit): Get user data
• get_collection(path, limit): Get generic collection data

Examples

Process AI Analysis with jq

# Using Poetry
poetry run epump-inspector ai-analysis --limit 100 | jq '.data[] | {id: ._id, user: .user_id, created: .timestamp}'
poetry run epump-inspector ai-feedback | jq '[.data[] | select(.positive == true)] | length'

# Using direct Python
python inspector.py ai-analysis --limit 100 | jq '.data[] | {id: ._id, user: .user_id, created: .timestamp}'
python inspector.py ai-feedback | jq '[.data[] | select(.positive == true)] | length'

Export to CSV

# Using Poetry
poetry run epump-inspector users | jq -r '.data[] | [._id, .email, .created_at] | @csv' > users.csv

# Using direct Python
python inspector.py users | jq -r '.data[] | [._id, .email, .created_at] | @csv' > users.csv

Filter by Date

# Using Poetry
poetry run epump-inspector workouts | jq '.data[] | select(.date >= "2024-01-01")'

# Using direct Python
python inspector.py workouts | jq '.data[] | select(.date >= "2024-01-01")'

Error Handling

Errors are returned as JSON:

{
  "error": "Error message",
  "command": "command_name"
}

Security Notes

• Store Firebase credentials securely
• Never commit service account files to version control
• Use environment variables for sensitive data
• Limit service account permissions to read-only access when possible