# SunTrace3D -- AI Agent Integration Guide

> This document explains how AI agents (chatbots, virtual assistants, MCP tools) can integrate with SunTrace3D to create solar panel analysis sessions for users. No API key required.

## Overview

AI agents can guide users through solar panel analysis by creating sessions that pre-configure the Solar Panel Wizard. The agent creates a session via API, receives a viewer URL, and sends it to the user. When the user opens the link, a 3D model generates (~1-2 minutes, loading animation shown) and the wizard opens with pre-configured settings.

## How It Works

1. **Agent creates a session** via `POST https://suntrace3d.com/api/mcp-sessions` with location, wizard goal, and optional roof coordinates
2. **Agent sends the `viewerUrl`** from the response to the user
3. User clicks the link -> model generates (~1-2 min) -> wizard opens with pre-configured settings

## Quick Start (Python)

```python
import requests

data = requests.post("https://suntrace3d.com/api/mcp-sessions", json={
    "agentName": "MyBot",
    "latitude": 48.8566,
    "longitude": 2.3522,
    "wizardGoal": "maximize_energy",
    "roofLat": 48.8568,
    "roofLng": 2.3520,
}).json()

print(f"Send to user: {data['viewerUrl']}")
```

## Quick Start (JavaScript)

```javascript
const res = await fetch("https://suntrace3d.com/api/mcp-sessions", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    agentName: "MyBot",
    latitude: 48.8566,
    longitude: 2.3522,
    wizardGoal: "maximize_energy",
    roofLat: 48.8568,
    roofLng: 2.3520,
  }),
});
const data = await res.json();
console.log(`Send to user: ${data.viewerUrl}`);
```

## Simplest Integration (No API Call)

Construct a URL directly -- no session creation needed:

`https://suntrace3d.com/viewer?lat=48.8566&lng=2.3522&wizard=maximize_energy`

This skips session tracking but still opens the viewer with the wizard pre-configured.

## API Reference

### Create Session

`POST https://suntrace3d.com/api/mcp-sessions`

**Request Body (JSON):**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agentName` | string | Yes | Your agent/bot name (max 100 chars) |
| `latitude` | number | Yes | Location center latitude |
| `longitude` | number | Yes | Location center longitude |
| `wizardGoal` | string | No | `maximize_energy`, `cover_bill`, `maximize_roi`, `environmental` |
| `wizardKwh` | number | No | Monthly kWh consumption (required when `wizardGoal` is `cover_bill`) |
| `roofLat` | number | No | Precise roof latitude for auto-click |
| `roofLng` | number | No | Precise roof longitude for auto-click |

**Response (JSON):**

| Field | Description |
|-------|-------------|
| `sessionId` | Unique session identifier |
| `viewerUrl` | Full URL to send to the user |
| `status` | `created` or `model_ready` (if SD model already cached) |
| `modelStatus` | `not_generated`, `processing`, or `ready` |
| `agentName` | Your agent name (echoed back) |
| `detectedPlatform` | Detected AI platform (e.g. `openai`, `anthropic`, `unknown`) |

**Response Headers:**

| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Maximum requests per window |
| `X-RateLimit-Remaining` | Requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the window resets |

### Check Session Status

`GET https://suntrace3d.com/api/mcp-sessions/{sessionId}`

Returns the current session state including `status`, `modelStatus`, panel data (if placed), and energy results (if calculated).

## Wizard Goals

| Goal | Behavior |
|------|----------|
| `maximize_energy` | Fill the entire roof surface with panels for maximum annual kWh |
| `cover_bill` | Place enough panels to match the user's monthly electricity consumption (`wizardKwh` required) |
| `maximize_roi` | Place panels optimizing for fastest payback period |
| `environmental` | Maximize CO2 offset |

## Rate Limits

Requests are rate-limited per IP address. Known AI platform IPs (OpenAI, Anthropic) receive higher limits.

| Tier | Limit | Who |
|------|-------|-----|
| Whitelisted | 100/hr | Requests from known AI platform IP ranges (OpenAI, Anthropic) |
| Standard | 10/hr | Requests with recognized AI User-Agent but unverified IP |
| Unknown | 5/hr | All other requests |

When the rate limit is exceeded, the API returns HTTP 429 with `X-RateLimit-*` headers indicating when to retry.

## Important Notes

- **No pre-generation**: The 3D model generates when the user opens the link (~1-2 min). Pro users automatically get HD quality; free users get SD.
- **Pro tier required**: The Solar Panel Wizard requires a Pro subscription (EUR 9/mo). Free users see an upgrade prompt when the wizard tries to open.
- **Auto-click**: When `roofLat`/`roofLng` are provided, the system auto-detects the roof surface. If detection misses, the user clicks manually.
- **Session expiry**: Sessions expire after 48 hours.
- **No API key**: The MCP sessions endpoint does not require authentication -- only rate limiting applies.

## Documentation

- [LLM Product Overview](https://suntrace3d.com/llms.txt): What SunTrace3D is and what it can do
- [LLM Agent Integration Guide](https://suntrace3d.com/llms-agent.txt): This file
- [LLM Documentation (full)](https://suntrace3d.com/llms-full.txt): Complete user guide + API reference + agent integration in a single file
- [API Reference (Markdown)](https://suntrace3d.com/docs/api-reference.md): Full API documentation including Partner API
- [Interactive API Docs](https://suntrace3d.com/docs/api): Interactive API documentation with code examples