Human API

Integrate Onairos Human API for memory-enhanced LLM calls.

Use production endpoint:
- Base URL: https://human-api.onairos.io/v1
- Auth: Authorization: Bearer <ONAIROS_API_KEY>
- User context auth: x-jwt-token: <USER_ONAIROS_JWT_FROM_CONSENT_FLOW>

Model selection:
- Human API is OpenAI-compatible. Pass the target model in the normal model field.
- Use the exact model ID, not the display name.
- OpenRouter-style IDs look like provider/model, for example openai/gpt-4. Exact available IDs change, so verify before hard-coding.
- To find model IDs in OpenRouter:
  1. Open https://openrouter.ai/models and copy the API model ID from the model page.
  2. Or call: curl https://openrouter.ai/api/v1/models
  3. Read the data[].id field and use that exact string as model.
- The models API also includes useful metadata such as name, context length, pricing, modality, and supported parameters. Use that before choosing max_tokens, tools, images, or provider-specific options.

User context:
- Use onairos.userContext for app-provided, request-local information that can personalize the answer.
- This is different from {onairos_memory}. {onairos_memory} asks Human API to inject long-term user memory. userContext is what the developer's app already knows right now.
- Good userContext inputs: current screen, selected item, current task, location or locale when consented, plan tier, in-app preferences, recent app actions, app-specific constraints, basket/cart contents, active project, user goals, and temporary state.
- Do not put API keys, passwords, private tokens, raw logs, or unnecessary sensitive data in userContext.
- Keep it concise. Prefer structured JSON when the app has fields; use a string when the app only has a short note.

String userContext example:
onairos: {
  userContext: "User is comparing running shoes, prefers neutral colors, has a $120 budget, and is shopping from the product detail page."
}

JSON userContext example:
onairos: {
  userContext: {
    currentPage: "product_detail",
    currentGoal: "choose a comfortable everyday running shoe",
    selectedProduct: {
      name: "Nike Pegasus",
      category: "running_shoes",
      priceUsd: 118
    },
    appPreferences: {
      units: "imperial",
      tone: "concise"
    },
    constraints: ["budget_under_120", "neutral_colors", "daily_wear"]
  }
}

JavaScript example:
import OpenAI from "openai";

const onairosClient = new OpenAI({
  apiKey: process.env.ONAIROS_API_KEY,
  baseURL: "https://human-api.onairos.io/v1",
  defaultHeaders: {
    "x-jwt-token": userJwt
  }
});

const response = await onairosClient.chat.completions.create({
  model: "openai/gpt-4o-mini",
  messages: [
    {
      role: "user",
      content: "Use {onairos_memory} and the current app context. Recommend the next action."
    }
  ],
  onairos: {
    userContext: {
      currentPage: "dashboard",
      currentGoal: "help the user make the next decision"
    }
  },
  max_tokens: 300
});

Integration rules:
1. Get the user JWT from the Onairos consent flow or SDK callback; do not ask for user passwords.
2. Include {onairos_memory} only when the response should use Onairos long-term memory.
3. Use onairos.userContext for request-local app state. It can be a string or JSON object.
4. If the same app context is already present in the conversation history, avoid repeating it every turn. Send only changed context or the current state that matters.
5. Human API strips the raw onairos object before forwarding to the model provider.
6. Keep developer keys server-side when possible.