i2-api

Imported from AI-ModCon/genesis-skills (skills/amsc-skills/i2-api/SKILL.md). Install upstream with npx skills add AI-ModCon/genesis-skills --skill i2-api. Copyright stays with the author.

AmSC i2 API

Use scripted workflows. Prefer the bundled scripts over hand-written curl commands.

Prerequisites

1. Go to https://api.i2-core.american-science-cloud.org/
2. Log in with your AmSC Google credentials
3. Click "API Key Manager" in the upper right corner
4. Generate a key
5. Set the environment variable:

export AMSC_I2_API_KEY=<your-key>

6. Ensure Python >= 3.10 with the requests package installed:

python3 -m pip install requests

IMPORTANT: Never hardcode API keys in source code. Always use environment variables.

Quick Start

1. Validate your key:

python3 scripts/key_manager.py status

2. List available models:

python3 scripts/i2_api_call.py list-models

3. Send a chat message:

python3 scripts/i2_api_call.py chat --model claude-sonnet --message "Hello, world"

Key Management

Use scripts/key_manager.py for key validation and spend tracking.

• Check if key is set and valid:

python3 scripts/key_manager.py status

• Check budget and current spend:

python3 scripts/key_manager.py spend

• Machine-readable output:

python3 scripts/key_manager.py status --json
python3 scripts/key_manager.py spend --json

Notes:

• Key is read from AMSC_I2_API_KEY environment variable
• Allow up to 5 seconds after an API call for spend logs to update

Model Discovery and Selection

Inspect Available Models

• List all model IDs grouped by mode:

python3 scripts/i2_api_call.py list-models

• Get detailed metadata for all models:

python3 scripts/i2_api_call.py model-info

• Get metadata for a specific model:

python3 scripts/i2_api_call.py model-info --model claude-sonnet

• Extract a specific property across all models:

python3 scripts/i2_api_call.py model-info --property supports_prompt_caching

Select the Best Model

Use scripts/select_model.py to find the optimal model for your requirements.

CLI filter mode -- specify requirements as flags:

python3 scripts/select_model.py \
  --mode chat \
  --vision required \
  --reasoning high \
  --tools required \
  --min-context 100000 \
  --caching preferred \
  --optimize cost

Natural language mode -- describe requirements as text:

python3 scripts/select_model.py \
  --describe "I need a model for coding tasks with function calling, \
  at least 128K context, and prompt caching. Cost is important."

Interactive interview mode -- answer prompts:

python3 scripts/select_model.py --interview

Available filter flags:

Chat Completions

Basic chat call:

python3 scripts/i2_api_call.py chat \
  --model claude-sonnet \
  --message "Explain quantum entanglement in one paragraph"

With a system prompt:

python3 scripts/i2_api_call.py chat \
  --model claude-sonnet \
  --system "You are a concise technical writer." \
  --message "Explain quantum entanglement"

Streaming response:

python3 scripts/i2_api_call.py chat \
  --model claude-sonnet \
  --message "Write a short story" \
  --stream

With token limit:

python3 scripts/i2_api_call.py chat \
  --model claude-haiku \
  --message "Summarize this text" \
  --max-tokens 256

With retry on transient failures:

python3 scripts/i2_api_call.py chat \
  --model claude-sonnet \
  --message "Hello" \
  --max-retries 3

Embeddings

Generate an embedding:

python3 scripts/i2_api_call.py embed \
  --model cohere-embed-english-v3 \
  --input "The quick brown fox jumps over the lazy dog"

Raw JSON output:

python3 scripts/i2_api_call.py embed \
  --model cohere-embed-v4 \
  --input "Sample text" \
  --json

Cost Management

Estimate cost before a call:

python3 scripts/i2_api_call.py cost-estimate \
  --model claude-sonnet \
  --input-tokens 1000 \
  --output-tokens 500

Check current spend:

python3 scripts/key_manager.py spend

Notes:

• After a call, the true cost is in the x-litellm-response-cost response header
• Use --json with i2_api_call.py subcommands to see full response headers
• Use smaller/cheaper models (haiku, gpt-oss-20b) for routine tasks; escalate to larger models only when needed

Claude Code Setup

Source the env var template to configure Claude Code with i2 as the backend:

source references/claude-code-env.sh

Or add the contents of references/claude-code-env.sh to your shell profile (~/.zshrc or ~/.bashrc).

After sourcing, verify the variables are set:

env | grep ANTHROPIC

Then start Claude Code normally:

cd my-project
claude

See references/claude-code-env.sh for all configurable variables and their descriptions.

LangChain Integration

The i2 API is OpenAI-compatible. Use langchain-openai with the i2 base URL.

Chat Model

import os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="claude-sonnet",
    base_url="https://api.i2-core.american-science-cloud.org/v1",
    api_key=os.environ["AMSC_I2_API_KEY"],
)

response = llm.invoke("Explain quantum entanglement")
print(response.content)

Embeddings

import os
from langchain_openai import OpenAIEmbeddings

embeddings = OpenAIEmbeddings(
    model="cohere-embed-english-v3",
    base_url="https://api.i2-core.american-science-cloud.org/v1",
    api_key=os.environ["AMSC_I2_API_KEY"],
)

vector = embeddings.embed_query("Sample text")

Streaming

import os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="claude-sonnet",
    base_url="https://api.i2-core.american-science-cloud.org/v1",
    api_key=os.environ["AMSC_I2_API_KEY"],
    streaming=True,
)

for chunk in llm.stream("Write a short story"):
    print(chunk.content, end="", flush=True)

Retry Handling

Always wrap inference calls in retry logic for production use:

import os
import time
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="claude-sonnet",
    base_url="https://api.i2-core.american-science-cloud.org/v1",
    api_key=os.environ["AMSC_I2_API_KEY"],
    max_retries=3,
    timeout=600,
)

Network Issues

SSL Certificate Errors

If you use Netskope or similar VPN software, register the CA certificate bundle:

# Python
export REQUESTS_CA_BUNDLE=/path/to/ca-cert.pem
export SSL_CERT_FILE=/path/to/ca-cert.pem

# Node.js
export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem

Contact your IT support to obtain the CA certificate bundle.

Timeout Errors

Use --timeout to increase the request timeout:

python3 scripts/i2_api_call.py chat \
  --model claude-opus \
  --message "Write a detailed analysis" \
  --timeout 600

Transient Network Errors

Use --max-retries for automatic retry with exponential backoff:

python3 scripts/i2_api_call.py chat \
  --model claude-sonnet \
  --message "Hello" \
  --max-retries 5

Retry sleep follows min(1 * 2^attempt, 30) seconds between attempts.