Define and document public API in __init__.py

[cnicholas]

Problem

The package has no clearly defined public API. Users don't know:

• What can be imported from processbehavior
• What is public vs private/internal
• What the recommended usage patterns are

Current State

processbehavior/__init__.py is empty (2 blank lines).

Target State

Clear, documented public API with examples:

# processbehavior/__init__.py

"""
processbehavior: Statistical Process Control for Python
========================================================

A spec-driven package for computing control chart statistics with tidy outputs.

Basic usage:
    >>> import pandas as pd
    >>> from processbehavior import perform_analysis
    >>> 
    >>> df = pd.DataFrame({
    ...     'machine': ['A', 'A', 'B', 'B'],
    ...     'measurement': [10.1, 10.2, 9.8, 9.9]
    ... })
    >>> 
    >>> spec = {
    ...     'analysis_type': 'Imr',
    ...     'response_var': 'measurement',
    ...     'rsg_vars': ['machine']
    ... }
    >>> 
    >>> result = perform_analysis(df, spec)
"""

from processbehavior.analysis import Analysis, perform_analysis
from processbehavior.specification import AnalysisSpecification
from processbehavior.dataset import AnalysisDataSet

__version__ = '0.1.0'

__all__ = [
    # Main functions
    'perform_analysis',
    
    # Classes
    'Analysis',
    'AnalysisSpecification', 
    'AnalysisDataSet',
]

Tasks

• Create processbehavior/version.py with __version__ = '0.1.0'
• Write module-level docstring with overview and example
• Import all public classes and functions
• Define __all__ to control from processbehavior import *
• Add __version__ attribute
• Consider exporting statistical constants (or keep them internal)
• Write docstrings for all public classes/functions
• Update README.md with correct import examples
• Add "API Reference" section to README

Examples to Include in Docs

Basic IMR Analysis

from processbehavior import perform_analysis

spec = {
    'analysis_type': 'Imr',
    'response_var': 'value',
    'rsg_vars': ['machine']
}
result = perform_analysis(df, spec)

XbarS Analysis

from processbehavior import Analysis

spec = {
    'analysis_type': 'Xbar',
    'response_var': 'measurement', 
    'rsg_vars': ['line', 'shift'],
    'time_var': 'timestamp',
    'round_to': 3
}

analysis = Analysis(df, spec)
result = analysis.calculate()

Benefits

• ✅ Clear user-facing API
• ✅ Better discoverability (IDE autocomplete)
• ✅ Prevents users from importing internal/private functions
• ✅ Professional package experience
• ✅ Easier to maintain API stability

Priority

🟠 HIGH - Required before PyPI release

Estimated Effort

~20-30 minutes

Dependencies

• Requires Issue CRITICAL: Fix package structure - code not in processbehavior/ directory #21 (package structure) to be completed first