# pseudocode — basic LLM completion
response = await ctx.llm.complete(
    prompt="your prompt text",
    model="<model-name>"       # see supported models table above
)
# response is a string containing the LLM output

# pseudocode — completion with system message
response = await ctx.llm.complete(
    prompt=user_query,
    system="role/persona instructions for the LLM",
    model="<model-name>"
)

# pseudocode — structured output
response = await ctx.llm.complete(
    prompt="your extraction/analysis prompt",
    response_format="json",
    schema=YourPydanticModel,    # validated automatically
    model="<model-name>"
)
# response is a validated instance of YourPydanticModel

# pseudocode — streaming completion
async for chunk in ctx.llm.stream(prompt="...", model="<model-name>"):
    # process each chunk as it arrives
    ...

# pseudocode — using LLM options
response = await ctx.llm.complete(
    prompt="...",
    model="<model-name>",
    temperature=0.7,
    max_tokens=1000,
    ...
)

# Tokens are tracked per-command automatically
# View usage via API: GET /api/v1/usage

from huitzo_sdk.errors import LLMError

try:
    response = await ctx.llm.complete(prompt="...", model="gpt-4o")
except LLMError as e:
    ctx.log.error(f"LLM failed: {e.provider} - {e.message}")
    # e.provider: "openai" or "anthropic"
    # e.model: The model that failed
    # e.status_code: HTTP status if applicable

@command("notify", namespace="alerts")
async def notify(args: Args, ctx: Context) -> dict:
    await ctx.email.send(
        to="[email protected]",
        subject="Alert: Action Required",
        body="Your report is ready for review."
    )
    return {"sent": True}

await ctx.email.send(
    to="[email protected]",
    subject="Weekly Report",
    html="""
    <h1>Weekly Report</h1>
    <p>Here are your metrics:</p>
    <ul>
        <li>Revenue: $10,000</li>
        <li>Users: 150</li>
    </ul>
    """,
)

# PDF attachment
pdf_bytes = generate_pdf_report(data)

await ctx.email.send(
    to="[email protected]",
    subject="Your Report",
    body="Please find your report attached.",
    attachments=[
        {
            "filename": "report.pdf",
            "content": pdf_bytes,
            "content_type": "application/pdf"
        }
    ]
)

await ctx.email.send(
    to=["[email protected]", "[email protected]"],
    cc=["[email protected]"],
    bcc=["[email protected]"],
    subject="Team Update",
    body="..."
)

# pseudocode — sending a template-based email
await ctx.email.send_template(
    to="[email protected]",
    template_id="<your-template-id>",    # provider-specific template ID
    template_data={                       # variables to fill in the template
        "name": "...",
        "report_url": "..."
    }
)

@command("fetch-data", namespace="api")
async def fetch_data(args: Args, ctx: Context) -> dict:
    response = await ctx.http.get(
        "https://api.example.com/data",
        headers={"Authorization": f"Bearer {args.api_key}"}
    )
    return response  # Parsed JSON

response = await ctx.http.post(
    "https://api.example.com/submit",
    json={"name": "value", "count": 42}
)

response = await ctx.http.get(
    "https://api.example.com/data",
    headers={"X-Custom-Header": "value"},
    params={"page": 1, "limit": 100},
    timeout=60,  # seconds
)

response = await ctx.http.post(
    "https://api.example.com/upload",
    data={"field": "value"},  # Form data
    files={"document": file_bytes},
)

response = await ctx.http.put(
    "https://api.example.com/resource/123",
    json={"updated": True}
)

response = await ctx.http.delete(
    "https://api.example.com/resource/123"
)

# huitzo.yaml
services:
  http:
    required: true
    allowed_domains:
      - "api.example.com"
      - "*.trusted-domain.org"

# pseudocode — assumes the tenant's HTTP integration has
# base_url = https://api.weather.example.com
response = await ctx.http.get(
    "/v1/forecast",
    params={"latitude": 37.77, "longitude": -122.42, "current": "temperature_2m"},
)

from huitzo_sdk.errors import HTTPError, HTTPSecurityError

try:
    response = await ctx.http.get("https://api.example.com/data")
except HTTPSecurityError as e:
    ctx.log.error(f"Domain not allowed: {e.domain}")
    # e.domain: The blocked domain
    # e.allowed_domains: List of allowed domains
except HTTPError as e:
    ctx.log.error(f"HTTP request failed: {e.status_code}")
    # e.url: Request URL
    # e.method: HTTP method
    # e.status_code: Response status
    # e.response_body: Response body (truncated)

@command("alert", namespace="notifications")
async def alert(args: Args, ctx: Context) -> dict:
    await ctx.telegram.send(
        chat_id=args.chat_id,  # User or group chat ID
        message="Alert: System status changed to WARNING"
    )
    return {"sent": True}

await ctx.telegram.send(
    chat_id="123456789",
    message="*Bold* and _italic_ text\n\n`code block`",
    parse_mode="Markdown"  # or "HTML"
)

pdf_bytes = generate_report()

await ctx.telegram.send_document(
    chat_id="123456789",
    document=pdf_bytes,
    filename="report.pdf",
    caption="Your weekly report"
)

await ctx.telegram.send_photo(
    chat_id="123456789",
    photo=image_bytes,
    caption="Chart: Revenue over time"
)

# This code works with ANY storage backend
@command("process-data", namespace="analytics")
async def process_data(args: Args, ctx: Context) -> dict:
    df = await ctx.files.read_excel(args.file_path)  # Works everywhere
    result = analyze(df)
    await ctx.files.write("output/report.csv", result.to_csv())  # Works everywhere
    return {"status": "complete"}

@command("analyze-excel", namespace="data")
async def analyze_excel(args: Args, ctx: Context) -> dict:
    # Returns pandas DataFrame
    df = await ctx.files.read_excel(args.file_path)

    # Specific sheet
    df = await ctx.files.read_excel(args.file_path, sheet="Sales")

    return {"rows": len(df), "columns": list(df.columns)}

df = await ctx.files.read_csv(args.file_path)
df = await ctx.files.read_csv(args.file_path, delimiter=";", encoding="utf-8")

data = await ctx.files.read_json(args.file_path)

# Write CSV
await ctx.files.write("output/report.csv", df.to_csv(index=False))

# Write JSON
await ctx.files.write("output/data.json", json.dumps(data, indent=2))

# Write binary
await ctx.files.write("output/report.pdf", pdf_bytes, binary=True)

info = await ctx.files.info(args.file_path)
# Returns: {"size": 1024, "created": datetime, "modified": datetime, "type": "xlsx"}

files = await ctx.files.list("uploads/")
# Returns: [{"name": "data.xlsx", "size": 1024, "modified": datetime}, ...]

if await ctx.files.exists("uploads/data.xlsx"):
    df = await ctx.files.read_excel("uploads/data.xlsx")

# Generate presigned URL (for object storage backends)
url = await ctx.files.get_url("output/report.pdf", expires=3600)  # 1 hour
return {"download_url": url}

# huitzo.yaml
services:
  files:
    max_size_mb: 50       # Stricter than platform default
    allowed_types:
      - .csv
      - .xlsx
      - .json

# Pack writes to "output/report.pdf"
await ctx.files.write("output/report.pdf", data)

# Platform stores at: tenant/{tenant_id}/output/report.pdf
# Other tenants cannot access this file

# huitzo.yaml
commands:
  - name: "generate-report"
    permissions:
      - "llm:complete"       # LLM completion
      - "llm:stream"         # LLM streaming
      - "email:send"         # Send emails
      - "telegram:send"      # Send Telegram messages
      - "http:request"       # External HTTP requests
      - "files:read"         # Read files
      - "files:write"        # Write files

# ✅ Good: Use smaller model for simple tasks
summary = await ctx.llm.complete(prompt=simple_prompt, model="gpt-4o-mini")

# ✅ Good: Use larger model for complex reasoning
analysis = await ctx.llm.complete(prompt=complex_prompt, model="gpt-4o")

# ✅ Good: Graceful degradation
try:
    await ctx.email.send(to=user_email, subject="Report", body=content)
except EmailError:
    ctx.log.warning("Email failed, saving to storage instead")
    await ctx.storage.save("pending-email", {"to": user_email, "content": content})

# ✅ Good: Batch operations where possible
# Instead of 100 individual LLM calls, batch into fewer calls with more content

# ❌ Bad: Hardcoded API key
response = await ctx.http.get(url, headers={"Authorization": "Bearer sk-xxx"})

# ✅ Good: Use environment variables (platform secrets)
api_key = ctx.env.require("EXTERNAL_API_KEY")
response = await ctx.http.get(url, headers={"Authorization": f"Bearer {api_key}"})

# huitzo.yaml
secrets:
  user_required:
    - name: "PLAID_CLIENT_ID"
      description: "Your Plaid client ID"
      help_url: "https://dashboard.plaid.com/developers/keys"

    - name: "PLAID_SECRET"
      description: "Your Plaid secret key"
      help_url: "https://dashboard.plaid.com/developers/keys"

  user_optional:
    - name: "PREMIUM_DATA_KEY"
      description: "Optional: Premium data provider API key"

# pseudocode — accessing user secrets in a command

# Required secret → raises SecretsError if the user hasn't configured it
api_key = ctx.secrets.require("SECRET_NAME")

# Optional secret → returns None if not set
optional_key = ctx.secrets.get("OPTIONAL_SECRET_NAME")

# Use the credentials with your external service
result = await external_service.call(api_key=api_key, ...)

# Conditionally use optional features
if optional_key:
    result = await enrich_result(result, optional_key)

# pseudocode — secrets error handling pattern

try:
    api_key = ctx.secrets.require("SECRET_NAME")
except SecretsError:
    # Return user-friendly guidance pointing to Settings → Pack Secrets
    return {"error": "...", "help": "Add your key in Settings → Pack Secrets"}

try:
    data = await external_api.call(api_key, ...)
except AuthenticationError:
    # Wrap as ExternalAPIError with actionable message
    raise ExternalAPIError(service="...", message="Key invalid. Update in Settings → Pack Secrets.")

   # Verify the key works
   valid = await service.validate_key(api_key)
   if not valid:
       raise ExternalAPIError(
           service="service-name",
           message="API key validation failed. Please check your key."
       )

   return {"status": "configured", "valid": True}

# huitzo.yaml — pseudocode
services:
  db: {}                     # required to receive ctx.db at runtime
db_integrations:             # optional name allowlist (omit to allow any)
  - "primary"
  - "warehouse"

# pseudocode — read rows
rows = await ctx.db.query(
    "primary",                                 # integration name
    "SELECT id, email FROM users WHERE id = $1",
    user_id,
    timeout=10,
)
# rows is a list[dict[str, Any]] with one entry per row.

# pseudocode — INSERT / UPDATE / DELETE
n = await ctx.db.execute(
    "primary",
    "UPDATE users SET active = $1 WHERE id = $2",
    True, user_id,
)
# n is the integer row count reported by the engine.

# pseudocode — multi-statement transaction (commits on clean exit, rolls back on raise)
async with ctx.db.transaction("primary") as txn:
    await txn.execute("INSERT INTO orders (id, total) VALUES ($1, $2)", order_id, 99)
    await txn.execute("UPDATE inventory SET qty = qty - 1 WHERE sku = $1", sku)

from huitzo_sdk.errors import DatabaseError

try:
    rows = await ctx.db.query("primary", "SELECT 1")
except DatabaseError as e:
    ctx.log.error(f"DB query failed on {e.integration!r}: {e.message}")

from huitzo_sdk import command, Context

@command("github-issue", namespace="devtools")
async def github_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,
            "body": args.body
        }
    )
    return {"issue_number": result["number"], "url": result["html_url"]}

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

secrets:
  user_required:
    - name: "GITHUB_TOKEN"
      description: "Your GitHub personal access token"
      help_url: "https://github.com/settings/tokens"

from huitzo_sdk.errors import MCPError, MCPConnectionError, MCPToolError

try:
    result = await ctx.mcp.call("github", "create_issue", {...})
except MCPConnectionError:
    ctx.log.error("GitHub MCP server unavailable")
    return {"error": "GitHub integration temporarily unavailable"}
except MCPToolError as e:
    ctx.log.error(f"GitHub tool failed: {e.message}")
    raise