pack:
  name: "my-company-analytics"
  namespace: "analytics"
  version: "1.0.0"
  description: "Business analytics and reporting tools"
  visibility: "organization"
  author: "My Company"
  license: "proprietary"

commands:
  - name: "generate-report"
    description: "Generate analytics report"
    entry_point: "my_company_analytics.commands.report:generate_report"
    permissions: ["llm:complete"]
    timeout: 300
    queue: "long"

  - name: "quick-summary"
    description: "Get quick data summary"
    entry_point: "my_company_analytics.commands.summary:quick_summary"
    permissions: []
    timeout: 30
    queue: "fast"

data_types:
  - name: "reports"
    description: "Generated report data"
    ttl_days: 90

  - name: "cache"
    description: "Temporary calculation cache"
    ttl_days: 7

services:
  llm:
    required: true
    models: ["gpt-4o-mini", "claude-sonnet"]
  email:
    required: false
  telegram:
    required: false

secrets:
  user_required:
    - name: "ANALYTICS_API_KEY"
      description: "Your analytics provider API key"
      help_url: "https://analytics.example.com/api-keys"
  user_optional:
    - name: "PREMIUM_API_KEY"
      description: "Optional premium tier API key"

metadata:
  homepage: "https://example.com/analytics-pack"
  repository: "https://github.com/example/analytics-pack"
  documentation: "https://docs.example.com/analytics"
  keywords: ["analytics", "reporting", "business-intelligence"]
  category: "business"

pack:
  name: "my-pack"           # Unique identifier (kebab-case)
  namespace: "mypack"       # Command namespace (lowercase, no dashes)
  version: "1.0.0"          # Semantic version
  description: "Short description of what the pack does"

pack:
  # ... required fields ...

  visibility: "organization"  # public | unlisted | organization | private
  author: "Your Name"         # Pack author or company
  author_email: "[email protected]"  # Author email
  license: "MIT"              # License identifier
  min_sdk_version: "2.0.0"    # Minimum SDK version required
  min_platform_version: "2.0.0"  # Minimum platform version required

  # Python dependencies beyond huitzo-sdk (which is always included)
  dependencies:
    - "pydantic>=2.0"
    - "requests>=2.31"

  # Dev-only dependencies
  dev_dependencies:
    - "pytest>=9.0"
    - "ruff>=0.14"

  # Pricing (marketplace only)
  pricing:
    model: "one-time"         # one-time | subscription | usage
    price: 49                 # USD (0 = free)

# Get shareable pack ID and link
$ huitzo pack share
Pack ID: pack_a1b2c3d4e5f6
Direct URL: https://app.huitzo.com/packs/pack_a1b2c3d4e5f6

# Client installs via pack ID
$ huitzo pack install pack_a1b2c3d4e5f6

pack:
  pricing:
    model: "one-time"
    price: 49

pack:
  pricing:
    model: "one-time"           # one-time | subscription | usage
    price: 49                   # USD (0 = free, minimum $5 for paid)
    currency: "usd"             # Only USD initially

    # Subscription-only fields (v0.1+)
    billing_period: "monthly"   # monthly | annual
    trial_days: 14              # Free trial period

    # Usage-based fields (v2.5+)
    per_execution: 0.05         # USD per command execution
    monthly_minimum: 5          # Optional minimum monthly charge

pack:
  pricing:
    model: "one-time"
    price: 49

pack:
  pricing:
    model: "subscription"
    price: 19
    billing_period: "monthly"
    trial_days: 14

pack:
  pricing:
    model: "usage"
    per_execution: 0.05
    monthly_minimum: 5

pack:
  pricing:
    model: "one-time"
    price: 0

pack:
  name: "claims-processor"
  pricing:
    model: "one-time"
    price: 49

pack:
  name: "analytics-dashboard"
  pricing:
    model: "subscription"
    price: 19
    billing_period: "monthly"
    trial_days: 7

pack:
  name: "document-parser"
  pricing:
    model: "usage"
    per_execution: 0.05
    monthly_minimum: 5

# Update pricing
$ huitzo pack update-pricing --price 59

# Publish with new pricing
$ huitzo pack publish

deployment:
  cloud_capable: true          # Can run in Huitzo cloud (default: true)
  self_hosted_capable: true    # Can run on customer infrastructure (default: true)
  edge_capable: false          # Can run on edge devices (default: false)
  offline_capable: false       # Can operate without network (default: false)
  requires_internet: true      # Requires internet for functionality (default: true)

# Example: Pack that only works in cloud (requires cloud LLM APIs)
deployment:
  cloud_capable: true
  self_hosted_capable: false
  requires_internet: true

# Example: Pack that works everywhere (no external dependencies)
deployment:
  cloud_capable: true
  self_hosted_capable: true
  edge_capable: true        # Future
  offline_capable: true     # Future
  requires_internet: false

# Example: Pack designed for regulated environments
deployment:
  cloud_capable: false       # No cloud for compliance
  self_hosted_capable: true
  edge_capable: true         # Future: air-gapped support
  offline_capable: true      # Future
  requires_internet: false

resources:
  min_memory_mb: 256           # Minimum memory to execute
  recommended_memory_mb: 512   # Recommended for performance
  requires_gpu: false          # GPU required for execution

resources:
  # Future: Hardware acceleration preferences
  # accelerator_preference: "cuda|tensorrt|onnx|cpu"
  # max_latency_ms: 100
  # power_budget_watts: 50

embedded_models:
  - id: "custom-ner"
    format: "onnx"             # onnx | pytorch | tensorflow
    size_mb: 128
    quantization: "int8"       # none | fp16 | int8
    description: "Custom NER model for entity extraction"

  - id: "summarizer"
    format: "onnx"
    size_mb: 256
    quantization: "fp16"
    description: "Text summarization model"

commands:
  - name: "hello"
    description: "Say hello"
    entry_point: "my_pack.commands.hello:hello_world"

commands:
  - name: "analyze-data"
    description: "Analyze dataset and generate insights"
    entry_point: "my_pack.commands.analyze:analyze_data"
    permissions:
      - "llm:complete"
      - "storage:write"
    timeout: 300
    queue: "long"
    retries: 3
    output_format: "json"
    deprecated: false
    deprecation_message: null

# pseudocode — scheduled command configuration
commands:
  - name: "daily-research"
    description: "Fetch and summarize daily news"
    timeout: 300
    queue: "medium"
    schedule: "0 8 * * 1-5"    # Mon-Fri at 8:00 AM UTC

commands:
  - name: "heavy-analysis"
    description: "Analyze large datasets"
    resources:
      tier: "standard"        # standard | compute | gpu
      timeout_seconds: 300    # Max execution time
      memory_hint: "256MB"    # Helps platform optimize scheduling
      cpu_hint: "0.5"         # Relative CPU weight (0.1 - 2.0)

┌─────────────────────────────────────────────────────────────────┐
│  1. During `huitzo pack dev` and `huitzo pack test`                       │
│     → Execution times are collected per command                 │
│                                                                  │
│  2. During `huitzo pack build`                                        │
│     → Statistics computed: p50, p95, max execution time         │
│     → Embedded in pack metadata                                  │
│                                                                  │
│  3. At runtime (production)                                      │
│     → Platform uses 2-5x multiplier on p95 time                 │
│     → Assigns to appropriate queue                               │
└─────────────────────────────────────────────────────────────────┘

def select_queue(p95_time: float) -> str:
    estimated_max = p95_time * 3  # 3x safety multiplier

    if estimated_max <= 5:
        return "fast"
    elif estimated_max <= 60:
        return "medium"
    else:
        return "long"

$ huitzo stats

Command Statistics (from 47 test runs):

COMMAND              P50      P95      MAX      QUEUE (auto)
get-user            0.02s    0.05s    0.08s    fast
analyze-data        2.10s    4.50s    6.20s    medium
generate-report    12.30s   45.00s   62.00s   long

commands:
  - name: "my-command"
    queue: "long"  # Force long queue regardless of stats

permissions:
  - "llm:complete"      # LLM completion API
  - "llm:stream"        # LLM streaming API
  - "email:send"        # Send emails
  - "telegram:send"     # Send Telegram messages
  - "storage:read"      # Read from storage
  - "storage:write"     # Write to storage
  - "http:request"      # Make external HTTP requests
  - "files:read"        # Read uploaded files
  - "files:write"       # Write files
  - "mcp:call"          # Call MCP server tools
  - "ssh:execute"       # Execute commands on SSH targets

data_types:
  - name: "conversations"
    description: "Chat conversation history"
    ttl_days: 90
    scope: "user"

  - name: "settings"
    description: "User preferences and settings"
    ttl_days: null  # Never expires
    scope: "user"

  - name: "cache"
    description: "Temporary calculation cache"
    ttl_days: 1
    scope: "tenant"

services:
  llm:
    required: true
    models:
      - "gpt-4o-mini"
      - "gpt-4o"
      - "claude-sonnet"
    default_model: "gpt-4o-mini"

  email:
    required: false

  telegram:
    required: false

  http:
    required: true
    allowed_domains:
      - "api.example.com"
      - "data.example.org"

services:
  llm:
    required: true
    models:                    # Supported models
      - "gpt-4o-mini"
      - "gpt-4o"
      - "claude-sonnet"
      - "claude-haiku"
    default_model: "gpt-4o-mini"  # Default if not specified
    max_tokens: 4096              # Max tokens per request
    temperature: 0.7              # Default temperature

services:
  http:
    required: true
    allowed_domains:           # Whitelist of allowed domains
      - "api.example.com"
      - "*.example.org"        # Wildcard supported
    timeout: 60                # Default timeout
    max_redirects: 5           # Max redirect follows

# huitzo.yaml — pseudocode
services:
  db: {}
db_integrations:
  - "primary"
  - "warehouse"

mcp_servers:
  - name: github
    type: stdio
    command: ["uvx", "mcp-server-github"]
    env:
      GITHUB_TOKEN: "${secrets.GITHUB_TOKEN}"

mcp_servers:
  - name: postgres-remote
    type: http
    url: "https://mcp.example.com/postgres"
    headers:
      Authorization: "Bearer ${secrets.MCP_API_KEY}"
    timeout: 30

mcp_servers:
  - name: github
    type: stdio
    command: ["uvx", "mcp-server-github"]
    env:
      GITHUB_TOKEN: "${secrets.GITHUB_TOKEN}"    # From user secrets
      GITHUB_ENTERPRISE_URL: "${secrets.GH_URL}" # Optional enterprise URL

secrets:
  user_required:
    - name: "GITHUB_TOKEN"
      description: "Your GitHub personal access token"
      help_url: "https://github.com/settings/tokens"
  user_optional:
    - name: "GH_URL"
      description: "GitHub Enterprise URL (optional)"

mcp_servers:
  # Local GitHub MCP server
  - name: github
    type: stdio
    command: ["uvx", "mcp-server-github"]
    env:
      GITHUB_TOKEN: "${secrets.GITHUB_TOKEN}"

  # Local PostgreSQL MCP server
  - name: postgres
    type: stdio
    command: ["uvx", "mcp-server-postgres"]
    env:
      DATABASE_URL: "${secrets.DATABASE_URL}"

  # Remote Slack MCP server
  - name: slack
    type: http
    url: "https://mcp.company.com/slack"
    headers:
      Authorization: "Bearer ${secrets.SLACK_MCP_TOKEN}"

from huitzo_sdk import command, Context

@command("create-issue", namespace="devtools")
async def create_issue(args: Args, ctx: Context) -> dict:
    """Create a GitHub issue using MCP."""
    result = await ctx.mcp.call(
        server="github",
        tool="create_issue",
        arguments={
            "owner": args.owner,
            "repo": args.repo,
            "title": args.title
        }
    )
    return {"issue_number": result["number"]}

ssh_targets:
  allowed:
    - "*"          # Allow all user-registered targets

ssh_targets:
  allowed:
    - "gpu-cluster"
    - "preprocessing-server"

pack:
  name: "ml-trainer"
  namespace: "ml"
  version: "1.0.0"
  description: "Train and deploy ML models on your GPU clusters"

commands:
  - name: "train"
    description: "Train a model on remote GPU"
    permissions: ["storage:write"]
    timeout: 3600
    queue: "long"

ssh_targets:
  allowed:
    - "*"          # User decides which GPUs to use

secrets:
  user_required:
    - name: "FINANCIAL_API_KEY"
      description: "Your API key from massive.com"
      help_url: "https://massive.com/developers/api-keys"

    - name: "TRADING_API_SECRET"
      description: "Trading platform secret key"
      help_url: "https://trading.example.com/api"

  user_optional:
    - name: "PREMIUM_API_KEY"
      description: "Optional premium tier API key for enhanced features"

from huitzo_sdk import command, Context
from huitzo_sdk.errors import SecretsError

@command("fetch-data", namespace="finance")
async def fetch_data(args: Args, ctx: Context) -> dict:
    # Required secret - raises SecretsError if missing
    api_key = ctx.secrets.require("FINANCIAL_API_KEY")

    # Optional secret - returns None if missing
    premium_key = ctx.secrets.get("PREMIUM_API_KEY")

    # Check existence
    if ctx.secrets.exists("PREMIUM_API_KEY"):
        # Use premium features
        pass

    # Call external API with user's key
    response = await ctx.http.get(
        "https://api.massive.com/data",
        headers={"Authorization": f"Bearer {api_key}"}
    )

    return response

metadata:
  homepage: "https://example.com/my-pack"
  repository: "https://github.com/example/my-pack"
  documentation: "https://docs.example.com/my-pack"
  changelog: "https://github.com/example/my-pack/blob/main/CHANGELOG.md"
  keywords:
    - "analytics"
    - "reporting"
    - "data"
  category: "business"
  icon: "chart-bar"           # Icon name (Lucide icons)
  screenshots:
    - "https://example.com/screenshot1.png"
    - "https://example.com/screenshot2.png"

huitzo pack validate

❌ Error: pack.name must be kebab-case
   Found: "MyPack"
   Expected: "my-pack"

❌ Error: commands[0].timeout exceeds queue limit
   Command: "slow-task" (timeout: 120)
   Queue: "fast" (max: 5s)
   Fix: Change queue to "medium" or "long"

❌ Error: Unknown permission "database:query"
   Command: "fetch-data"
   Valid permissions: llm:complete, email:send, ...

# huitzo.yaml - Financial Intelligence Pack

pack:
  name: "plutus-financial"
  namespace: "plutus"
  version: "2.1.0"
  description: "Portfolio analysis and financial reporting tools"
  visibility: "organization"
  author: "Huitzo Inc."
  license: "proprietary"
  min_sdk_version: "2.0.0"

# Deployment capabilities
deployment:
  cloud_capable: true
  self_hosted_capable: true
  edge_capable: false          # Future
  offline_capable: false       # Future
  requires_internet: true      # Needs market data APIs

# Pack-level resource requirements
resources:
  min_memory_mb: 256
  recommended_memory_mb: 512
  requires_gpu: false

# Embedded models (future edge deployment)
embedded_models: []

commands:
  - name: "analyze-portfolio"
    description: "Analyze investment portfolio performance"
    permissions:
      - "llm:complete"
      - "http:request"
      - "storage:write"
    timeout: 300
    queue: "long"
    retries: 2
    resources:
      tier: "standard"
      timeout_seconds: 300

  - name: "generate-report"
    description: "Generate PDF investment report"
    permissions:
      - "llm:complete"
      - "email:send"
      - "storage:read"
      - "files:write"
    timeout: 600
    queue: "long"
    resources:
      tier: "standard"
      timeout_seconds: 600

  - name: "get-quote"
    description: "Get current stock quote"
    permissions:
      - "http:request"
    timeout: 10
    queue: "fast"
    resources:
      tier: "standard"
      timeout_seconds: 10

  - name: "list-holdings"
    description: "List portfolio holdings"
    permissions:
      - "storage:read"
    timeout: 30
    queue: "fast"
    resources:
      tier: "standard"
      timeout_seconds: 30

data_types:
  - name: "portfolios"
    description: "User portfolio data"
    ttl_days: null
    scope: "user"

  - name: "reports"
    description: "Generated reports"
    ttl_days: 365
    scope: "user"

  - name: "market_cache"
    description: "Market data cache"
    ttl_days: 1
    scope: "tenant"

services:
  llm:
    required: true
    models: ["gpt-4o-mini", "gpt-4o"]
    default_model: "gpt-4o-mini"

  email:
    required: true

  http:
    required: true
    allowed_domains:
      - "api.polygon.io"
      - "api.alpaca.markets"

secrets:
  user_required:
    - name: "POLYGON_API_KEY"
      description: "Your Polygon.io API key for market data"
      help_url: "https://polygon.io/dashboard/api-keys"
  user_optional:
    - name: "ALPACA_API_KEY"
      description: "Alpaca Markets API key for trading data"
      help_url: "https://alpaca.markets/docs/api-references/broker-api/"

metadata:
  homepage: "https://huitzo.com/packs/plutus"
  documentation: "https://docs.huitzo.ai/packs/plutus"
  keywords: ["finance", "portfolio", "investment", "analysis"]
  category: "finance"
  icon: "trending-up"

# pseudocode — proposed integrations section

integrations:
  - name: "salesforce"
    class: "my_pack.integrations.salesforce:SalesforceIntegration"
    required_secrets:
      - name: "SALESFORCE_KEY"
        description: "Your Salesforce API key"
        help_url: "https://developer.salesforce.com/docs"
    allowed_domains:
      - "*.salesforce.com"
    shared_secrets: []  # secrets shared with consuming packs (empty = none)

# pseudocode — proposed dependencies section

dependencies:
  - pack: "@acme/salesforce-connector"
    version: ">=1.0.0"
    integrity: "sha256:abc123..."  # content hash pinning

# pseudocode — proposed file_mounts section

file_mounts:
  - mount_point: "/mnt/s3-reports"
    driver: "s3"
    config:
      bucket: "company-reports"
      region: "us-east-1"
    required_secrets:
      - "AWS_ACCESS_KEY_ID"
      - "AWS_SECRET_ACCESS_KEY"

# pseudocode — proposed events section

events:
  publishes:
    - type: "invoice.received"
      description: "Emitted when an invoice is detected in email"
      payload_schema:
        sender: "string"
        amount: "number"

  subscribes:
    - type: "invoice.received"
      handler: "my_pack.handlers:on_invoice_received"
      max_concurrency: 5

# pseudocode — proposed pipelines section

pipelines:
  invoice-processor:
    description: "Extract invoice data from email"
    timeout: 300
    stages:
      - command: "source:scan-inbox"
        config:
          filter: "subject:invoice"
      - command: "action:extract-fields"
      - command: "dest:save-to-sheet"

# pseudocode — proposed config section

config:
  http.timeout: 60
  http.max_retries: 5
  llm.default_model: "gpt-4o"

commands:
  - name: "heavy-report"
    config:
      http.timeout: 300  # command-level override