Common Files

Every Cirron CLI project includes a set of common files that provide essential infrastructure, configuration, and project management capabilities. These files are generated regardless of your chosen template or model type.

Project Structure

The common files create a standardized project structure:

my-project/
├── src/                    # Source code (framework-specific)
├── tests/                  # Test files
├── models/                 # Saved models
├── checkpoints/            # Training checkpoints
├── logs/                   # Training and application logs
├── data/                   # Data directory
│   └── sample/            # Sample data (optional)
├── notebooks/              # Jupyter notebooks (optional)
├── requirements.txt        # Python dependencies
├── Dockerfile             # Container configuration
├── .gitignore             # Git ignore rules
├── README.md              # Project documentation
├── .env.example           # Environment variables template
└── cirron.yaml            # Cirron configuration

Generated Files

Dockerfile

Production-ready container configuration:

FROM python:3.9-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Copy requirements first for better caching
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy source code
COPY src/ ./src/
COPY models/ ./models/

# Expose port for inference server
EXPOSE 8000

# Default command
CMD ["python", "src/inference.py"]

Features:

Multi-stage optimization: Efficient layer caching
Security: Minimal base image with essential dependencies
Production ready: Exposed ports and proper working directory
Flexible: Easy to customize for different deployment scenarios

.gitignore

Comprehensive Git ignore rules for ML projects:

# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
*.egg-info/
.installed.cfg
*.egg

# Virtual environments
venv/
env/
ENV/

# ML specific
*.pkl
*.joblib
*.h5
*.pth
*.onnx
models/*.bin
checkpoints/
logs/
data/raw/
data/processed/
.wandb/
mlruns/

# Jupyter
.ipynb_checkpoints/
*.ipynb

# IDE
.vscode/
.idea/
*.swp
*.swo

# OS
.DS_Store
Thumbs.db

# Environment variables
.env
.env.local

Coverage:

Python artifacts: Compiled files, packages, virtual environments
ML artifacts: Model files, checkpoints, logs, experiment tracking
Development tools: IDE files, Jupyter notebooks
System files: OS-specific files
Security: Environment variable files

README.md

Comprehensive project documentation:

# My Project

A classification model built with Cirron CLI.

## Quick Start

### Setup Environment
```bash
pip install -r requirements.txt

Run Tests

cirron test

Train Model (if training template)

python src/train.py

Run Inference

python src/inference.py

Build Container

cirron build

Deploy

cirron deploy

Project Structure

my-project/
├── src/
│   ├── model.py          # Model definition
│   ├── inference.py      # Inference script
│   ├── train.py          # Training script (if applicable)
│   └── data_loader.py    # Data loading utilities
├── tests/
│   ├── test_model.py     # Model tests
│   ├── test_inference.py # Inference tests
│   └── test_data.py      # Data validation tests
├── models/               # Saved models
├── checkpoints/          # Training checkpoints
├── logs/                 # Training logs
├── data/sample/          # Sample data
├── notebooks/            # Jupyter notebooks
├── requirements.txt      # Python dependencies
├── Dockerfile           # Container definition
└── cirron.yaml         # Cirron configuration

Cirron Commands

cirron test - Run all tests
cirron test --model - Test model loading
cirron test --build - Test container build
cirron build - Build the project
cirron deploy - Deploy to your environment
cirron status - Check project status
cirron logs - View deployment logs

Environment Variables

Use cirron env commands to manage environment variables:

cirron env list
cirron env set MODEL_PATH /path/to/model
cirron env delete OLD_VAR

Model Information

Framework: pytorch
Model Type: classification
Python Version: 3.9+

Development

Make changes to your model in src/model.py
Test locally: cirron test
Build container: cirron build
Deploy: cirron deploy --env staging

**Features:**
- **Quick start guide**: Immediate setup instructions
- **Command reference**: All available Cirron CLI commands
- **Project structure**: Visual representation of the project
- **Development workflow**: Step-by-step development process

### .env.example

Environment variables template:

```bash
# Model configuration
MODEL_PATH=models/best_model.pth
BATCH_SIZE=32
DEVICE=cuda

# Data paths
DATA_PATH=data/
TRAINING_DATA_PATH=data/train/
VALIDATION_DATA_PATH=data/val/

# API configuration
API_HOST=0.0.0.0
API_PORT=8000

# Logging
LOG_LEVEL=INFO
LOG_PATH=logs/

# Training configuration
LEARNING_RATE=0.001
NUM_EPOCHS=10
CHECKPOINT_DIR=checkpoints/

Categories:

Model configuration: Paths, batch sizes, device settings
Data paths: Training and validation data locations
API settings: Server configuration for inference
Logging: Log levels and output paths
Training: Hyperparameters and checkpoint settings

Test Files

test_model.py

Model validation tests:

import unittest
import sys
import os
sys.path.append(os.path.join(os.path.dirname(__file__), '..', 'src'))

from model import create_model

class TestModel(unittest.TestCase):
    def setUp(self):
        self.model = create_model()
    
    def test_model_creation(self):
        """Test that model can be created"""
        self.assertIsNotNone(self.model)
    
    def test_model_attributes(self):
        """Test model has required attributes/methods"""
        # Add framework-specific tests based on template
        if hasattr(self.model, 'forward'):  # PyTorch
            self.assertTrue(callable(self.model.forward))
        elif hasattr(self.model, 'predict'):  # sklearn or custom
            self.assertTrue(callable(self.model.predict))

if __name__ == '__main__':
    unittest.main()

test_inference.py

Inference validation tests:

import unittest
import sys
import os
sys.path.append(os.path.join(os.path.dirname(__file__), '..', 'src'))

from inference import ModelInference

class TestInference(unittest.TestCase):
    def setUp(self):
        self.inference = ModelInference()
    
    def test_inference_creation(self):
        """Test that inference object can be created"""
        self.assertIsNotNone(self.inference)
        self.assertIsNotNone(self.inference.model)
    
    def test_preprocess_method(self):
        """Test preprocessing method exists and works"""
        self.assertTrue(hasattr(self.inference, 'preprocess'))
        self.assertTrue(callable(self.inference.preprocess))
    
    def test_predict_method(self):
        """Test prediction method exists"""
        self.assertTrue(hasattr(self.inference, 'predict'))
        self.assertTrue(callable(self.inference.predict))

if __name__ == '__main__':
    unittest.main()

test_data.py

Data validation tests:

import unittest
import sys
import os
sys.path.append(os.path.join(os.path.dirname(__file__), '..', 'src'))

class TestData(unittest.TestCase):
    def test_data_directory_exists(self):
        """Test that data directory structure exists"""
        if os.path.exists('data'):
            self.assertTrue(os.path.isdir('data'))
    
    def test_sample_data_format(self):
        """Test sample data format if it exists"""
        # Add specific data validation tests based on your requirements
        pass

if __name__ == '__main__':
    unittest.main()

Optional Components

Sample Data

When --include-sample-data is specified, sample datasets are created:

Classification Sample Data

feature1,feature2,feature3,label
2,2.3,3.4,0
1,3.2,4.3,1
0,4.1,5.2,0
3,5.4,6.5,1
1,6.2,7.3,0

Regression Sample Data

feature1,feature2,feature3,target
2,2.3,3.4,10.5
1,3.2,4.3,15.2
0,4.1,5.2,18.7
3,5.4,6.5,22.1
1,6.2,7.3,25.8

Jupyter Notebook

When --include-notebook is specified, an exploration notebook is created:

# explore.ipynb
{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# My Project - Exploration Notebook\n",
        "\n",
        "This notebook provides a starting point for exploring your classification model.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "import sys\n",
        "import os\n",
        "sys.path.append('../src')\n",
        "\n",
        "import numpy as np\n",
        "import matplotlib.pyplot as plt\n",
        "import pandas as pd\n",
        "\n",
        "# Import your model\n",
        "from model import create_model\n",
        "from inference import ModelInference\n"
      ]
    }
    // ... additional cells for data exploration, model testing, etc.
  ]
}

Configuration Options

Directory Structure

The common files create these directories:

tests/: Unit tests and integration tests
models/: Saved model files
checkpoints/: Training checkpoints
logs/: Application and training logs
data/sample/: Sample datasets (optional)
notebooks/: Jupyter notebooks (optional)

File Permissions

All generated files use appropriate permissions:

Readable: All files are readable by the application
Writable: Logs, checkpoints, and models directories are writable
Executable: Scripts have appropriate execute permissions

Best Practices

Project Organization

Separation of concerns: Source code, tests, and data are clearly separated
Consistent naming: Standardized file and directory names
Documentation: Comprehensive README and inline documentation
Version control: Proper .gitignore for ML projects

Security

Environment variables: Sensitive configuration is externalized
Container security: Minimal base images and proper permissions
Data protection: Sample data doesn’t contain sensitive information

Development Workflow

Testing: Comprehensive test suite for all components
Documentation: Clear setup and usage instructions
Deployment: Production-ready container configuration
Monitoring: Logging and status checking capabilities

Customization

Modifying Common Files

You can customize the common files after project creation:

# Edit Dockerfile for custom requirements
vim Dockerfile

# Add custom environment variables
cp .env.example .env
vim .env

# Customize README for your specific project
vim README.md

Adding Custom Components

# Add custom scripts
mkdir scripts
touch scripts/custom_script.py

# Add configuration files
touch config.yaml

# Add documentation
mkdir docs
touch docs/api.md

Integration with Cirron CLI

The common files integrate seamlessly with Cirron CLI commands:

# Test the project
cirron test

# Build container (uses Dockerfile)
cirron build

# Deploy (uses environment variables)
cirron deploy

# Check status (uses project structure)
cirron status

# View logs (uses logs directory)
cirron logs

Next Steps

Template Generation - How templates are created
PyTorch Template - Deep learning with PyTorch
TensorFlow Template - Deep learning with TensorFlow
scikit-learn Template - Traditional ML algorithms
Custom Template - Custom implementations
CLI Commands - Learn about available CLI commands

Cirron CLI

Commands

Utils

Templates

Documentation Index

​Common Files

​Project Structure

​Generated Files

​Dockerfile

​.gitignore

​README.md

​Run Tests

​Train Model (if training template)

​Run Inference

​Build Container

​Deploy

​Project Structure

​Cirron Commands

​Environment Variables

​Model Information

​Development

​Test Files

​test_model.py

​test_inference.py

​test_data.py

​Optional Components

​Sample Data

​Classification Sample Data

​Regression Sample Data

​Jupyter Notebook

​Configuration Options

​Directory Structure

​File Permissions

​Best Practices

​Project Organization

​Security

​Development Workflow

​Customization

​Modifying Common Files

​Adding Custom Components

​Integration with Cirron CLI

​Next Steps

Common Files

Project Structure

Generated Files

Dockerfile

.gitignore

README.md

Run Tests

Train Model (if training template)

Run Inference

Build Container

Deploy

Project Structure

Cirron Commands

Environment Variables

Model Information

Development

Test Files

test_model.py

test_inference.py

test_data.py

Optional Components

Sample Data

Classification Sample Data

Regression Sample Data

Jupyter Notebook

Configuration Options

Directory Structure

File Permissions

Best Practices

Project Organization

Security

Development Workflow

Customization

Modifying Common Files

Adding Custom Components

Integration with Cirron CLI

Next Steps