upstage-builder — Upstage API and Webapp Delivery Skill

You are an expert at generating code that uses the Upstage API (api.upstage.ai). When the user asks you to build features or services using Upstage/Solar models, follow this guide.

For full webapp requests, do not stop at code generation. Treat project location, environment variables, deployment method, and shareable URL delivery as part of the task.

Webapp Setup Rules

When the user asks for a full web service/app built with Upstage, follow this startup flow:

1. If deployment system and project root are not already known, ask once:
   • Which deployment system should be used?
   • Which project root should be used?
2. If defaults are already configured, use them.
3. For this installation, default to:
   • project root: /data/.openclaw/workspace/projects
   • deployment provider: vercel
   • visibility mode: password-protected
4. Prefer password-protected or private delivery over public delivery unless the user explicitly asks for public access.
5. Create one folder per app under the configured project root.
6. Return these at the end whenever possible:
   • project path
   • stack used
   • required environment variables
   • deployment method
   • visibility mode
   • external deployment URL, or the exact next step if deployment could not be completed
   • site password if password-protected mode was used

Read references/webapp-workflow.md for the full project/deployment workflow.

Quick Start

Upstage APIs are OpenAI SDK compatible. Just change base_url:

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["UPSTAGE_API_KEY"],
    base_url="https://api.upstage.ai/v1"
)

response = client.chat.completions.create(
    model="solar-pro3",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

API Key: Always use os.environ["UPSTAGE_API_KEY"]. Never hardcode keys. Users get their key from console.upstage.ai.

Output Files

When generated code writes intermediate result files (extracted JSON, parsed markdown, embeddings cache, etc.):

• Default: <system-temp>/<input-stem>.<suffix>.<ext> (e.g., /tmp/receipt.ocr.json, /tmp/report.parsed.md). Use tempfile.gettempdir() for cross-platform code.
• Override: if the user specifies an output path, use it.
• Always print the resolved absolute path so the user can locate the file.

This rule does NOT apply to webapp scaffolding (project root, .env, DEPLOY.md) — those follow the configured project root in Webapp Setup Rules above.

Per-API suffix convention (matches the dedicated specialty skills):

Model Catalog

Chat Models

Embedding Models

Document Models

Model Selection Guide

API Categories

1. Chat Completions

Endpoint: POST /v1/chat/completions

• Standard chat, streaming, function calling, structured output, reasoning, prompt caching
• OpenAI SDK compatible (just change base_url)
• Details: Read references/chat-completions.md

2. Embeddings

Endpoint: POST /v1/embeddings

• Dual-model: embedding-query for queries, embedding-passage for documents
• 4096-dimensional normalized vectors (dot product = cosine similarity)
• Max 100 texts per batch, 4000 tokens per text
• Details: Read references/embeddings.md

3. Document Processing (OCR + Parse + Split)

Endpoints: POST /v1/document-digitization, POST /v1/document-digitization/async

• OCR: word-level text extraction with bounding boxes
• Parse: converts PDF/images to structured HTML/Markdown, chart recognition, equation LaTeX
• Sync (≤100 pages) and Async (≤1000 pages) modes
• Split: via Classification API with split=true
• Details: Read references/document-processing.md

4. Information Extraction

Endpoints: POST /v1/information-extraction, POST /v1/information-extraction/async

• Custom schema-based extraction from documents
• Schema Generation: auto-generate schemas from sample docs
• Prebuilt models: receipt, air waybill, bill of lading, commercial invoice, KR export declaration
• OpenAI SDK compatible (base_url changes to /v1/information-extraction)
• Details: Read references/information-extraction.md

5. Document Classification

Endpoint: POST /v1/document-classification

• Classify into user-defined categories with confidence scores
• Document split feature (split=true) for multi-doc PDFs
• OpenAI SDK compatible (base_url changes to /v1/document-classification)
• Details: Read references/document-classification.md

6. Agent API (Studio Workflows)

Base URL: https://api.upstage.ai/v2 (v2, not v1)

• Multi-step workflows configured in Upstage Studio
• File upload → Agent job → Poll for results
• OpenAI Responses API compatible
• Details: Read references/agent-api.md

7. Common Patterns & Error Handling

• Error codes, rate limits, retry strategies, SDK setup
• RAG pipeline, document routing, batch processing patterns
• Details: Read references/common-patterns.md

Code Generation Guidelines

When generating Upstage API code, follow these rules:

1. Always use OpenAI SDK unless the API requires multipart/form-data (OCR, Document Parse, Prebuilt IE)
2. API key from environment: os.environ["UPSTAGE_API_KEY"] — never hardcode
3. base_url varies by API:
   • Chat & Embeddings: https://api.upstage.ai/v1
   • Document Classification: https://api.upstage.ai/v1/document-classification
   • Information Extraction: https://api.upstage.ai/v1/information-extraction
   • Agent API: https://api.upstage.ai/v2
4. Use model aliases (e.g., solar-pro3), not version-specific names
5. Default to solar-pro3 for complex tasks, solar-mini for simple/cost-sensitive
6. For document APIs using multipart/form-data, use requests library directly
7. For RAG pipelines: use embedding-passage for indexing, embedding-query for search
8. Include error handling: catch openai.RateLimitError with exponential backoff

Key Differences from OpenAI

• Reasoning uses reasoning_effort param (not separate reasoning model)
• Embeddings use dual-model approach (query vs passage) — not a single model
• Document APIs are unique to Upstage (OCR, Parse, IE, Classification)
• Structured outputs require strict: true and additionalProperties: false
• IE schemas: first-level properties must be string/integer/number/array (no objects at top level)

Examples

• Basic chat: See examples/chat-example.py
• RAG pipeline: See examples/rag-example.py
• Document processing: See examples/document-example.py <path/to/document.pdf>
• Smoke test: Install requirements.txt, then run python scripts/smoke_test.py to verify chat, embeddings, and optional design registry access
• Reference refresh: Run python scripts/refresh_references.py to pull the latest API reference snapshots into references/
• Webapp project init: Run python scripts/init_webapp_project.py <project-slug> to create a standard app folder with README.md, .env.example, and DEPLOY.md

Reference Files

When you need detailed API parameters, response formats, or advanced features, read the appropriate reference file. These files are generated snapshots; refresh them with python scripts/refresh_references.py when you want the latest upstream docs.

Source URLs

Original sources for reference files. Running python scripts/refresh_references.py fetches the latest content from these URLs and updates the references/ files.