label-accelerator-sdk 1.0.0
Accelerate AI development with programmatic data labeling and weak supervision.
License: MIT
Requires Python: >=3.8
Keywords: weak supervision, data labeling, programmatic labeling, mlops, ai, machine learning

# Label Accelerator SDK

**Accelerate AI development with programmatic data labeling and weak supervision. Reduce labeling costs by 90% and time from months to minutes.**

## Why Label Accelerator?

The 80/20 rule in AI: 80% of effort goes to data preparation and labeling, 20% to actual model development. Manual data labeling is slow, expensive, and inconsistent. This SDK transforms your domain expertise into **programmatic heuristics** that label datasets at scale with human-like accuracy.

---

## Core Concepts

Instead of manually labeling thousands of examples, define a set of weighted **heuristics** based on your domain knowledge. The system evaluates how well each data point matches these rules, producing labels with confidence scores. Data that falls into uncertain ranges gets flagged for human review, optimizing your labeling budget.

---

## Installation

```bash
# Standard version
pip install label-accelerator-sdk

# For optimized performance (requires C++ compiler)
pip install label-accelerator-sdk[optimized]
```

---

## Quick Start

### Community Edition (Free)

```python
from label_accelerator import LabelingManager, Heuristic

# Define spam detection heuristics
spam_heuristics = [
    Heuristic('contains_spam_keywords', True, importance=5.0, sensitivity=5.0),
    Heuristic('has_suspicious_links', True, importance=4.0, sensitivity=4.0),
    Heuristic('text_length', 50, importance=2.0, sensitivity=1.5),
    Heuristic('excessive_caps_ratio', 0.3, importance=3.0, sensitivity=3.0)
]

# Initialize labeling manager
lm = LabelingManager(
    heuristics=spam_heuristics,
    positive_threshold=0.75,  # SPAM
    negative_threshold=0.35   # NOT_SPAM
)

# Label individual data points
email_features = {
    'contains_spam_keywords': True,
    'has_suspicious_links': True,
    'text_length': 45,
    'excessive_caps_ratio': 0.8
}

result = lm.label(email_features)
print(f"Label: {result.label}")
print(f"Confidence: {result.score:.3f}")
print(f"Needs review: {result.needs_review}")
```

### Professional Edition

```python
from label_accelerator import LabelingManager, Heuristic
import pandas as pd

# Initialize with license
lm = LabelingManager(
    heuristics=sentiment_heuristics,
    positive_threshold=0.70,
    negative_threshold=0.40,
    tier='professional',
    license_key='PRO-2026-12-31-XXXX-XXXX'
)

# Professional: Process entire DataFrames
df = pd.read_csv('unlabeled_reviews.csv')
labeled_df = lm.label_dataframe(df)

print(f"Labeled {len(labeled_df)} reviews")
print(f"Needs review: {labeled_df['needs_review'].sum()}")

# Access adaptive metrics
metrics = lm.get_metrics()
print(f"Adapted threshold: {metrics.current_threshold:.3f}")
print(f"Average confidence: {metrics.avg_score:.3f}")
```

### Enterprise Edition

```python
from label_accelerator import LabelingManager, HeuristicPresets

# Initialize with enterprise features
lm = LabelingManager(
    heuristics=HeuristicPresets.spam_detection_heuristics(),
    tier='enterprise',
    license_key='ENT-2026-12-31-XXXX-XXXX'
)

# Enterprise exclusive: Adjust heuristic weight calibration
lm.set_adjustment_factor(0.4)  # 60% expert weights, 40% algorithm-optimized

# Process large datasets with automatic weight optimization
for batch in large_dataset_batches:
    results = lm.label_dataframe(batch)

# View how the system adapted heuristic weights
metrics = lm.get_metrics()
if metrics.adaptive_weights:
    print("Heuristic weight optimizations:")
    for heuristic, change in metrics.weight_changes.items():
        print(f"  {heuristic}: {change:+.2%} from initial")
```

---

## Tier Comparison

| Feature                          |  Community |      Professional       |       Enterprise        |
|----------------------------------|------------|-------------------------|-------------------------|
| **Labels/month**                 | Unlimited* |      Unlimited          |       Unlimited         |
| **Standard Heuristics**          |    ✅      |          ✅            |          ✅             |
| **DataFrame Processing**         |    ❌      |          ✅            |          ✅             |
| **Adaptive Thresholds**          |    ❌      |          ✅            |          ✅             |
| **Quality Metrics**              |    ❌      |          ✅            |          ✅    Enhanced |
| **Weight Optimization**          |    ❌      |          ❌            |          ✅             |
| **Support**                      |  Community |         Email           |     Priority SLA         |
| **License validity**             |    N/A     |        Annual           |        Annual            |

*Community tier is free for evaluation. Production use requires registration.

---

## Enterprise Features

### Weight Calibration (Enterprise Exclusive)
Enterprise tier automatically optimizes heuristic weights based on data patterns:

```python
# Control the balance between expert and algorithm weights
lm.set_adjustment_factor(0.3)  # Default: 70% expert, 30% algorithm

# Factor range:
# 0.0 = 100% expert weights (trust configuration)
# 0.5 = 50/50 mix  
# 1.0 = 100% algorithm weights (full automation)
```

The algorithm tracks feature magnitudes and uses sqrt dampening to prevent extreme values from dominating, then mixes expert and algorithmic weights according to your adjustment factor.

---

## Core Features

### Programmatic Labeling Functions

Define domain expertise as configurable heuristics instead of manual rules.

```python
# Sentiment analysis heuristics
sentiment_heuristics = [
    Heuristic('positive_word_count', 5, importance=4.0, sensitivity=2.0),
    Heuristic('negative_word_count', 0, importance=4.0, sensitivity=3.0),
    Heuristic('has_negation', False, importance=3.0, sensitivity=5.0),
    Heuristic('text_length', 100, importance=1.5, sensitivity=1.0)
]
```

### Three-Way Classification

Generate POSITIVE, NEGATIVE, or ABSTAIN labels based on confidence thresholds.

```python
# Configurable decision boundaries
lm = LabelingManager(
    heuristics=heuristics,
    positive_threshold=0.75,  # High confidence for positive
    negative_threshold=0.35   # Low confidence for negative
    # Between 0.35-0.75 = ABSTAIN (human review needed)
)
```

### Heuristic Presets

```python
from label_accelerator import HeuristicPresets

# Ready-to-use configurations
spam_rules = HeuristicPresets.spam_detection_heuristics()
sentiment_rules = HeuristicPresets.sentiment_analysis_heuristics()
```

---

## Hybrid Model Integration

The SDK accepts **any predictive model** as an additional heuristic, creating powerful ensemble systems that combine expert rules, ML models, statistical models, and external APIs.

### ML Model Integration

```python
import joblib
from transformers import pipeline

# Load pre-trained models
bert_classifier = pipeline('sentiment-analysis', model='bert-base-uncased')
xgboost_model = joblib.load('fraud_detector.pkl')

# Define hybrid heuristics combining rules + ML models
fraud_heuristics = [
    # Traditional expert rules
    Heuristic('transaction_amount', 100, importance=3.0, sensitivity=2.0),
    Heuristic('time_of_day', 14, importance=2.0, sensitivity=1.5),
    
    # ML models as heuristics
    Heuristic('bert_sentiment_score', 0.8, importance=4.0, sensitivity=3.0),
    Heuristic('xgboost_risk_score', 0.3, importance=4.5, sensitivity=4.0)
]

# Process data with hybrid ensemble
def process_transaction(transaction_data):
    # Get ML model predictions
    text_sentiment = bert_classifier(transaction_data['description'])[0]['score']
    xgb_risk = xgboost_model.predict_proba([transaction_data['features']])[0][1]
    
    # Combine with traditional features
    hybrid_data = {
        'transaction_amount': transaction_data['amount'],
        'time_of_day': transaction_data['hour'],
        'bert_sentiment_score': text_sentiment,
        'xgboost_risk_score': xgb_risk
    }
    
    return lm.label(hybrid_data)
```

### Statistical Model Integration

```python
from scipy import stats
import requests

# Statistical and API-based models as heuristics
credit_heuristics = [
    # Expert domain rules
    Heuristic('debt_to_income_ratio', 0.3, importance=4.0, sensitivity=3.5),
    Heuristic('employment_years', 3, importance=3.0, sensitivity=2.0),
    
    # Statistical model
    Heuristic('credit_zscore', 0.5, importance=3.5, sensitivity=3.0),
    
    # External API service
    Heuristic('external_credit_api_score', 0.75, importance=4.0, sensitivity=3.5)
]

def evaluate_credit_application(applicant):
    # Calculate statistical metrics
    income_zscore = stats.zscore([applicant['income']] + historical_incomes)[0]
    credit_zscore = max(0, min(1, (income_zscore + 3) / 6))  # Normalize to 0-1
    
    # Call external credit bureau API
    api_response = requests.post('https://creditbureau-api.com/score', 
                                json={'ssn': applicant['ssn']})
    external_score = api_response.json()['credit_score'] / 850  # Normalize to 0-1
    
    # Combine all signals
    hybrid_data = {
        'debt_to_income_ratio': applicant['debt'] / applicant['income'],
        'employment_years': applicant['employment_years'],
        'credit_zscore': credit_zscore,
        'external_credit_api_score': external_score
    }
    
    return lm.label(hybrid_data)
```

### Benefits of Hybrid Ensembles

- **Best of all worlds**: Expert knowledge + ML power + statistical rigor + external data
- **Configurable weighting**: Control how much each model contributes via importance/sensitivity
- **Interpretable results**: Each model's contribution is transparent in the final score
- **Gradual adoption**: Start with rules, incrementally add models as they become available
- **Risk mitigation**: If one model fails, others compensate automatically

---

## Use Cases

### Email Spam Detection

```python
spam_heuristics = [
    Heuristic('contains_spam_keywords', True, 5.0, 5.0),    # Critical
    Heuristic('sender_reputation_score', 0.8, 3.0, 3.0),  # Important
    Heuristic('link_count', 2, 2.5, 2.0),                 # Moderate
    Heuristic('image_to_text_ratio', 0.3, 2.0, 2.0)       # Secondary
]
```

### Sentiment Analysis

```python
sentiment_heuristics = [
    Heuristic('positive_word_count', 3, 4.0, 2.0),
    Heuristic('negative_word_count', 1, 4.0, 3.0),
    Heuristic('has_intensifiers', True, 2.0, 1.5),
    Heuristic('punctuation_intensity', 0.1, 1.5, 1.5)
]
```

### Content Moderation

```python
moderation_heuristics = [
    Heuristic('contains_profanity', False, 5.0, 5.0),
    Heuristic('toxicity_score', 0.2, 4.0, 4.0),
    Heuristic('personal_attacks', False, 4.5, 5.0),
    Heuristic('context_appropriateness', 0.8, 3.0, 2.0)
]
```

---

## Heuristic Configuration

### Heuristic Parameters

```python
Heuristic(
    name='feature_name',         # Feature identifier
    reference=expected_value,    # Ideal/target value
    importance=1.0,             # Weight in final decision (1.0-5.0)
    sensitivity=1.5             # Strictness of comparison (1.0-5.0)
)
```

### Configuration Guidelines

| Importance | Meaning      | Use Case                |
|------------|--------------|-------------------------|
| 1.0 - 2.0  | Nice to have | Supporting indicators   |
| 2.0 - 3.0  | Moderate     | Standard features       |
| 3.0 - 4.0  | Important    | Key decision factors    |
| 4.0 - 5.0  | Critical     | Must-have requirements  |

| Sensitivity | Meaning     | Use Case                    |
|-------------|-------------|-----------------------------|
| 1.0 - 2.0   | Flexible    | Allow variations            |
| 2.0 - 3.0   | Moderate    | Standard strictness         |
| 3.0 - 4.0   | Strict      | Low tolerance for deviation |
| 4.0 - 5.0   | Very Strict | Near-exact match required   |

---

## API Reference

### LabelingManager

Main interface for programmatic labeling.

**Methods:**
- `__init__(heuristics, positive_threshold, negative_threshold, tier, license_key)` - Initialize manager
- `label(data)` - Label single data point (returns LabelingResult)
- `label_dataframe(df)` - Process DataFrame (Pro/Enterprise)
- `get_metrics()` - Performance statistics (Pro/Enterprise)
- `set_adjustment_factor(factor)` - Weight calibration (Enterprise)

### LabelingResult

Result of labeling operation.

**Attributes:**
- `label` (str): 'POSITIVE', 'NEGATIVE', or 'ABSTAIN'
- `score` (float): Confidence score (0.0-1.0)
- `needs_review` (bool): Whether human review is recommended

### Heuristic

Configuration for labeling rules.

**Parameters:**
- `name` (str): Feature name
- `reference` (Any): Target/ideal value
- `importance` (float): Feature weight (1.0-5.0)
- `sensitivity` (float): Comparison strictness (1.0-5.0)

---

## Professional & Enterprise Licensing

Professional and Enterprise tiers include:
- Adaptive threshold learning from labeling patterns
- Real-time quality metrics and insights
- Support for DataFrame batch processing
- Production-ready optimization algorithms
- Enterprise: Automatic heuristic weight calibration

**To purchase a license:**
- Professional: $299/month or $2,999/year
- Enterprise: Contact for custom pricing
- Email: jaimeajl@hotmail.com

**License format:**
- Professional: `PRO-YYYY-MM-DD-XXXX-XXXX`
- Enterprise: `ENT-YYYY-MM-DD-XXXX-XXXX`

---

## Migration from Manual Labeling

### Before:
```python
# Manual labeling workflow
labeled_data = []
for data_point in unlabeled_dataset:
    # Human manually reviews each example
    label = human_annotator.label(data_point)
    labeled_data.append((data_point, label))
    
# Months of work, high cost, potential inconsistency
```

### After:
```python
# Programmatic labeling with human review only for uncertain cases
lm = LabelingManager(heuristics=domain_rules)
for data_point in unlabeled_dataset:
    result = lm.label(data_point)
    if result.needs_review:
        # Only uncertain cases need human review
        human_review_queue.append(data_point)
    else:
        # Confident predictions are automatically labeled
        labeled_data.append((data_point, result.label))

# 90% reduction in manual work
```

---

## Integration with ML Pipelines

### Use Scores as Features
```python
# Generate labels and use confidence scores as ML features
results = [lm.label(data) for data in dataset]
df['weak_supervision_label'] = [r.label for r in results]
df['confidence_score'] = [r.score for r in results]

# Train final model using both original features + confidence scores
X = df[original_features + ['confidence_score']]
y = df['final_label']
model.fit(X, y)
```

### Active Learning Integration
```python
# Focus human effort on most uncertain examples
uncertain_examples = df[df['needs_review'] == True]
uncertain_examples = uncertain_examples.sort_values('confidence_score')

# Label most uncertain examples first for maximum learning impact
priority_queue = uncertain_examples.head(100)
```

---

## Frequently Asked Questions

### How accurate are the generated labels?
Accuracy depends on heuristic quality and domain. Well-designed heuristics achieve 70-90% precision, comparable to human annotators but at scale.

### Can I combine this with active learning?
Yes. Use confidence scores to identify uncertain examples for human review, creating a hybrid human+machine labeling pipeline.

### How do I handle imbalanced datasets?
Adjust positive/negative thresholds based on class distribution. For rare positive cases, lower positive_threshold to capture more candidates.

### What's the difference between importance and sensitivity?
- **Importance**: How much a heuristic contributes to the final score (weight)
- **Sensitivity**: How strictly deviations are penalized (tolerance)

### How does adaptive learning work?
- **Professional/Enterprise**: Automatically adjust decision thresholds based on score distributions after 10+ evaluations
- **Enterprise only**: Additionally optimizes individual heuristic weights based on data patterns

---

## Support

- **Documentation:** https://docs.labelaccelerator.ai
- **Community:** https://github.com/labelaccelerator/sdk/discussions  
- **Issues:** https://github.com/labelaccelerator/sdk/issues
- **Professional/Enterprise Support:** jaimeajl@hotmail.com

---

## License

MIT License for Community Edition. Professional and Enterprise editions are subject to commercial licensing terms.

© 2025 Label Accelerator SDK. Weak Supervision technology powered by Adaptive Formula.