# Onairos Agent Guide
# Copy this file into your AI assistant or code agent when integrating Onairos.

## Docs Root
https://docs.onairos.uk

## Identify The Product First
- Persona SDK: user consent flow, connectors, traits, preferences, raw memories, and inference.
- Human API: OpenAI-compatible LLM endpoint with automatic memory injection.

## Docs Map
- Quick Setup: https://docs.onairos.uk/quick-setup
- Persona Overview: https://docs.onairos.uk/persona
- Web Integration: https://docs.onairos.uk/integrate-web
- React Native Integration: https://docs.onairos.uk/mobile-integration
- Flutter Integration: https://docs.onairos.uk/flutter-integration
- Swift Integration: https://docs.onairos.uk/swift-integration
- Data Sources Overview: https://docs.onairos.uk/data-connectors
- Inference API: https://docs.onairos.uk/inference-api
- Example Usage: https://docs.onairos.uk/example-usage
- Human API: https://docs.onairos.uk/human-api
- LLM Install: https://docs.onairos.uk/llm-install

## Agent Navigation Rules
- Start with the platform guide before writing code.
- Use only the current public prop names and callback shapes from the docs.
- Do not use or document legacy examples unless the task is explicitly about migration.
- Use the returned `apiUrl` for follow-up Persona requests.
- For connector questions, open `https://docs.onairos.uk/data-connectors` first, then open the relevant connector detail page from the `Data Connectors` sidebar dropdown.
- Prefer the current public contract over older examples.

## Current Public Connector Surfaces
- Web connector flow: YouTube, LinkedIn, Reddit, Pinterest, X
- Web raw memories flow: ChatGPT, Claude, Gemini, Grok
- React Native connector flow: YouTube, Reddit, Spotify, Netflix, Sephora, Pinterest, LinkedIn, Gmail, ChatGPT, Claude, Gemini, Grok
- Current connector detail pages exist for: ChatGPT, Claude, Gemini, Grok, YouTube, Reddit, LinkedIn, Pinterest, X, Spotify, Netflix, Sephora, Gmail

## Magic Prompts By Platform

### Web
Run `npm install onairos`, then read `node_modules/onairos/llm.txt` and set up the Onairos web SDK with API key `{Your_API_Key}`.

### React Native
Run `npm install @onairos/react-native`, then read `node_modules/@onairos/react-native/docs/llm.txt` and set up the Onairos React Native SDK with API key `{Your_API_Key}`.

### Flutter
Run `dart pub add onairos`, then read the installed Onairos Flutter package's `llm.txt` guide and set up the Flutter SDK with API key `{Your_API_Key}`.

### Swift
Add the Swift package `https://github.com/onairos/onairos-swift-sdk`, then read that package's `llm.txt` guide and set up the Onairos Swift SDK with API key `{Your_API_Key}`.

## Persona SDK: Web

### Install
```bash
npm install onairos
```

### Current Web Contract
- Import from `onairos`
- Initialize once with `initializeApiKey({ apiKey })`
- Use `webpageName`, not `AppName`
- Use `onComplete(result)`, not `onResolved`
- Use `autoFetch`, not `auto`
- Use `requestData` as an array of scope ids such as `preferences`, `personality`, and `rawMemories`
- Web `autoFetch` defaults to `true`

### Minimal Example
```jsx
import { OnairosButton, initializeApiKey } from 'onairos';

await initializeApiKey({ apiKey: 'your_api_key' });

<OnairosButton
  webpageName="YourApp"
  requestData={['preferences', 'personality']}
  onComplete={(result) => {
    console.log(result.token);
    console.log(result.apiUrl);
    console.log(result.apiResponse);
  }}
/>
```

### Web Connector Rules
- `allowedPlatforms` filters the default connector list by display name or connector id.
- `allowedPlatforms` does not reorder the list to match caller order.
- `rawMemoriesOnly={true}` shows only LLM connectors and overrides `allowedPlatforms`.
- `rawMemoriesConfig` is only for extra raw-memory controls.
- Do not rely on legacy `priorityPlatform` to reorder the current web UI.

## Persona SDK: React Native

### Install
```bash
npm install @onairos/react-native
```

### Current React Native Contract
- Initialize once with `initializeApiKey({ apiKey })`
- Wrap the app in `PortalHost`
- Use `AppName`
- Use `onComplete(result)`
- Use `requestData` as an object keyed by consent ids such as `personality`, `preferences`, and `rawMemories`
- React Native `autoFetch` defaults to `false`
- Use `allowedPlatforms` for filtering and order
- Use `recommendedPlatforms` for the `Highly Recommended` badge only

### Minimal Example
```jsx
import React, { useEffect } from 'react';
import { View } from 'react-native';
import {
  PortalHost,
  OnairosButton,
  initializeApiKey
} from '@onairos/react-native';

export default function App() {
  useEffect(() => {
    initializeApiKey({ apiKey: 'your_api_key' });
  }, []);

  return (
    <PortalHost>
      <View>
        <OnairosButton
          AppName="YourApp"
          autoFetch={false}
          requestData={{
            personality: {
              name: 'Personality traits',
              description: 'Use traits and summaries in your app',
              reward: 'Deeper personalization'
            },
            preferences: {
              name: 'Preferences',
              description: 'Use inferred tastes and scoring signals',
              reward: 'Better recommendations'
            }
          }}
          allowedPlatforms={['chatgpt', 'youtube', 'linkedin']}
          recommendedPlatforms={['chatgpt', 'linkedin']}
          onComplete={(result) => {
            console.log(result.token);
            console.log(result.apiUrl);
            console.log(result.apiResponse);
          }}
        />
      </View>
    </PortalHost>
  );
}
```

### React Native Connector Rules
- `allowedPlatforms` filters connectors and preserves the exact order you pass in.
- `recommendedPlatforms` adds the badge only.
- `recommendedPlatforms` does not move connectors to the front.
- Do not rely on legacy `preferredPlatform` to reorder the current React Native UI.

## Persona SDK: Flutter

### Install
```bash
dart pub add onairos
```

### Current Flutter Contract
- Initialize with `initializeApiKey(...)`
- Render the `Onairos` widget
- Use `AppName`
- Use `returnLink` for the app URL scheme
- Use `requestData` as a map keyed by `basic`, `preferences`, and `personality`
- Use `onResolved(apiUrl, token, userData)`
- The current high-level Flutter wrapper does not expose public `allowedPlatforms` or `recommendedPlatforms`

### Minimal Example
```dart
import 'package:flutter/material.dart';
import 'package:onairos/initialize_api_key.dart';
import 'package:onairos/onairos.dart';

await initializeApiKey(
  apiKey: 'your_api_key',
  environment: 'production',
);

class OnairosDemo extends StatefulWidget {
  const OnairosDemo({super.key});

  @override
  State<OnairosDemo> createState() => _OnairosDemoState();
}

class _OnairosDemoState extends State<OnairosDemo> {
  @override
  Widget build(BuildContext context) {
    return Onairos(
      AppName: 'YourApp',
      returnLink: 'yourapp',
      requestData: {
        'basic': {
          'name': 'Basic Profile',
          'description': 'Required account basics',
          'reward': 'Required'
        },
        'preferences': {
          'name': 'Preferences',
          'description': 'Use inferred tastes in your app',
          'reward': 'Better recommendations'
        },
        'personality': {
          'name': 'Personality',
          'description': 'Use traits and summaries in your app',
          'reward': 'Deeper personalization'
        }
      },
      onResolved: (apiUrl, token, userData) {
        print(apiUrl);
        print(token);
        print(userData['apiResponse']);
      },
    );
  }
}
```

### Flutter Notes
- Older examples may show `personality_traits`, `sentiment_analysis`, or `auto`; do not use those for new docs or new integrations.
- `preferredPlatform` is not a reliable way to reorder the current wrapper UI.

## Persona SDK: Swift

### Add The Package
Use Xcode `File -> Add Package Dependencies` with:
```text
https://github.com/onairos/onairos-swift-sdk
```

### Current Swift Contract
- Configure `OnairosConfig`
- Call `OnairosSDK.shared.initialize(config:)`
- Create the button with `createConnectButton`
- Use `platforms` to control visible connectors and order
- Use `recommendedPlatforms` for badges only

### Minimal Example
```swift
import UIKit
import OnairosSDK

let config = OnairosConfig(
    apiKey: "your_api_key",
    environment: .production,
    googleClientID: "your-google-client-id.apps.googleusercontent.com",
    platforms: [.chatgpt, .youtube, .linkedin],
    recommendedPlatforms: [.chatgpt, .youtube],
    urlScheme: "yourapp",
    appName: "YourApp"
)

OnairosSDK.shared.initialize(config: config)

let button = OnairosSDK.shared.createConnectButton(text: "Connect your data") { result in
    switch result {
    case .success(let onboardingResult):
        switch onboardingResult {
        case .success(let data):
            print(data.apiURL)
            print(data.token)
            print(data.connectedPlatforms.keys)
        case .failure(let error):
            print(error.localizedDescription)
        }
    case .failure(let error):
        print(error.localizedDescription)
    }
}
```

## Returned Result Shape
- The SDK hands back a returned `apiUrl` plus a short-lived `token`
- When SDK fetch mode is enabled, use `apiResponse`
- Send `Input` only when you are making an inference request
- Common response patterns are:
  - traits/profile response
  - inference scores response
  - combined traits + inference response

## Human API
- Docs: https://docs.onairos.uk/human-api
- LLM install docs: https://docs.onairos.uk/llm-install
- Base URL: `https://developer.onairos.uk/v1`
- Use the normal OpenAI SDK shape
- Add the user's Onairos JWT in the `x-jwt-token` header
- Put `{onairos_memory}` in prompts when you want automatic memory injection

## Final Rules For Agents
- Use the platform page as the canonical integration source.
- Use the connector pages for connector-specific collection questions.
- Use the returned `apiUrl` and documented response fields in user-facing guidance.
- Prefer current docs and code behavior over older README snippets.