HarchOS Examples

Starter templates and example projects for common HarchOS workflows. Covers GPU training, LLM inference, data pipelines, pricing, monitoring, and multi-region deployment — all with carbon-aware scheduling built in.

Quick Start

# Install the HarchOS Python SDK
pip install harchos

# Install the HarchOS JS SDK (for TypeScript examples)
npm install harchos

# Clone this repo
git clone https://github.com/HarchCorp/harchos-examples.git
cd harchos-examples

# Pick an example and run
cd pricing/01-cost-estimate
python cost_estimate.py --gpu-type H100 --gpu-count 8 --hours 168

Example Catalog

PyTorch Training

#	Example	Language	Difficulty	Description
01	Basic ResNet-50	Python	🟢 Beginner	Train ResNet-50 on CIFAR-10 with a single GPU
02	Distributed DDP	Python	🟡 Intermediate	Multi-node DDP training with gradient accumulation
03	Carbon-Aware Training	Python	🔴 Advanced	Pause/resume training based on carbon intensity

LLM Inference

#	Example	Language	Difficulty	Description
01	Streaming Llama	Python + TypeScript	🟢 Beginner	Streaming SSE inference with Python server + TypeScript client
02	Quantized GPTQ	Python	🟡 Intermediate	4-bit quantized LLM with throughput benchmarking
03	RAG Pipeline	Python	🔴 Advanced	Retrieval-Augmented Generation with FAISS + LLM

Data Pipelines

#	Example	Language	Difficulty	Description
01	ETL Pipeline	Python	🟢 Beginner	Extract-Transform-Load with CSV → Parquet
02	Streaming Inference	Python	🟡 Intermediate	Real-time queue-based inference pipeline

💰 Pricing

#	Example	Language	Difficulty	Description
01	Cost Estimator	Python + TypeScript	🟢 Beginner	Calculate cost estimates for different GPU types and regions
02	Billing History	Python + TypeScript	🟡 Intermediate	Retrieve and analyze billing records with spending summaries
03	Price Comparison	Python + TypeScript	🟡 Intermediate	Compare prices across regions, tiers, and GPU types with carbon adjustment

📊 Monitoring

#	Example	Language	Difficulty	Description
01	Platform Metrics	Python + TypeScript	🟢 Beginner	Display platform-wide GPU, energy, and carbon metrics
02	Health Check	Python + TypeScript	🟢 Beginner	Detailed health check with sovereignty compliance and exit codes
03	Carbon Dashboard	Python + TypeScript	🔴 Advanced	Comprehensive carbon metrics dashboard with green window detection

🌍 Multi-Region

#	Example	Language	Difficulty	Description
01	Geo-Distributed	Python	🟡 Intermediate	Multi-region deployment with latency-based routing
02	Carbon-Optimized	Python	🔴 Advanced	Carbon-intensity-aware traffic routing across hubs
03	Pricing-Optimized	Python + TypeScript	🔴 Advanced	Deploy workloads optimized for pricing across regions with carbon and sovereignty constraints
04	Monitoring Dashboard	Python + TypeScript	🔴 Advanced	Cross-region monitoring dashboard with alerts

Requirements

• Python 3.9+
• HarchOS Python SDK (pip install harchos)
• Node.js 18+ (for TypeScript examples only)
• HarchOS JS SDK (npm install harchos, for TypeScript examples)

Project Structure

harchos-examples/
├── pytorch-training/              # GPU training examples
│   ├── 01-basic-resnet50/         #   Beginner: single-GPU training
│   ├── 02-distributed-ddp/        #   Intermediate: multi-node DDP
│   └── 03-carbon-aware-training/  #   Advanced: carbon-aware scheduling
├── llm-inference/                 # LLM serving examples
│   ├── 01-streaming-llama/        #   Beginner: SSE streaming (Python + TS)
│   ├── 02-quantized-gptq/         #   Intermediate: 4-bit GPTQ quantized
│   └── 03-rag-pipeline/           #   Advanced: RAG with FAISS
├── data-pipelines/                # Data processing examples
│   ├── 01-etl-pipeline/           #   Beginner: CSV → Parquet ETL
│   └── 02-streaming-inference/    #   Intermediate: real-time inference
├── pricing/                       # 💰 Pricing and billing examples
│   ├── 01-cost-estimate/          #   Beginner: cost estimation (Python + TS)
│   ├── 02-billing-history/        #   Intermediate: billing records (Python + TS)
│   └── 03-price-comparison/       #   Intermediate: cross-region comparison (Python + TS)
├── monitoring/                    # 📊 Platform monitoring examples
│   ├── 01-platform-metrics/       #   Beginner: platform metrics (Python + TS)
│   ├── 02-health-check/           #   Beginner: health monitoring (Python + TS)
│   └── 03-carbon-dashboard/       #   Advanced: carbon dashboard (Python + TS)
├── multi-hub/                     # Multi-hub deployment examples (legacy)
│   ├── 01-geo-distributed/        #   Intermediate: latency-based routing
│   └── 02-carbon-optimized/       #   Advanced: carbon-aware routing
├── multi-region/                  # 🌍 Multi-region deployment examples
│   ├── 03-pricing-optimized/      #   Advanced: pricing + carbon optimization (Python + TS)
│   └── 04-monitoring-dashboard/   #   Advanced: cross-region dashboard (Python + TS)
├── .github/workflows/ci.yml       # CI: lint, validate, structure check
├── README.md                      # This file
├── CONTRIBUTING.md                # Contribution guidelines
└── LICENSE                        # Apache 2.0

SDK Resources Used

Resource	Python SDK	JS SDK	API Endpoints
Pricing	client.pricing.*	client.pricing.*	GET /v1/pricing/plans, POST /v1/pricing/estimate, GET /v1/pricing/billing/*
Monitoring	client.monitoring.*	client.monitoring.*	GET /v1/monitoring/metrics, GET /v1/monitoring/health/detailed
Regions	client.regions.*	client.regions.*	GET /v1/regions
Carbon	client.carbon.*	—	GET /v1/carbon/*
Hubs	client.hubs.*	client.hubs.*	GET /v1/hubs

Best Practices

Carbon-Aware Scheduling

• Always set a carbon intensity threshold (--carbon-max) before deploying
• Use carbon-aware scheduling to defer workloads during high-carbon periods
• Prefer Ouarzazate (18 gCO2/kWh) and Dakhla (32 gCO2/kWh) for green compute

Sovereignty Enforcement

• Use --sovereign-only for workloads with data residency requirements
• Verify compliance frameworks (GDPR, CNDP, NDPR, PDPA) per region
• Ensure data stays within sovereignty boundaries

Cost Optimization

• Estimate costs before deploying — use the pricing examples
• Compare carbon-adjusted pricing with --include-carbon for true cost
• Choose enterprise tier for 5%+ volume discounts on 8+ GPU deployments

Monitoring

• Set up continuous health checks with --watch and exit codes
• Monitor GPU utilization for right-sizing (target 70-85%)
• Track carbon metrics to validate green scheduling effectiveness

Contributing

See CONTRIBUTING.md for guidelines on adding new examples.

License

Apache 2.0 — see LICENSE.