# seer-ai

An AI-powered oracle to verify outcomes for prediction markets using Google's Gemini API with grounding capabilities. Automatically resolves queries and can prepare blockchain transactions for prediction market contracts.

## Installation

```bash
npm install seer-ai
```

## Usage

### Basic Usage - Resolve a Query

Get a definitive answer (YES/NO/AMBIGUOUS) for past or current events:

```typescript
import { Seer } from 'seer-ai';

const seer = new Seer({ apiKey: 'your-gemini-api-key' });

const result = await seer.resolve('Was BTC above $60,000 on Oct 26, 2024?');

console.log(result.answer); // "YES: According to..."
console.log(result.sources); // Array of source URLs
```

### Predict Future Events

Get a probability-based prediction for future events:

```typescript
const prediction = await seer.predict('Will BTC be above $100,000 by Jan 1, 2026?');

console.log(prediction.answer); // "PREDICTION: YES — 75% probability. Market trends indicate..."
console.log(prediction.sources); // Array of source URLs
```

### Advanced Usage - Resolve and Prepare Blockchain Transaction

```typescript
import { Seer } from 'seer-ai';
import { ethers } from 'ethers';

const seer = new Seer({ apiKey: 'your-gemini-api-key' });

const result = await seer.resolveAndPrepareTx({
  query: 'Was BTC above $60,000 on Oct 26, 2025?',
  abi: ['function resolveMarket(uint256 outcome)'],
  contractAddress: '0x...',
  functionName: 'resolveMarket',
  paramsBuilder: (outcome) => [outcome === 'YES' ? 1 : 0],
  // Optional: broadcast transaction
  chainRpc: 'https://sepolia.infura.io/v3/YOUR_KEY',
  privateKey: '0x...', // Omit for transaction data only
});

if (result.status === 'resolved') {
  console.log('Answer:', result.answer);
  console.log('Transaction data:', result.data);
  console.log('To address:', result.to);
  if (result.txHash) {
    console.log('Transaction hash:', result.txHash);
  }
} else {
  console.log('Market not yet resolved:', result.answer);
}
```

## API

### Seer Class

**Constructor**
```typescript
new Seer({ apiKey: string })
```
- `apiKey`: Your Google Gemini API key

**Methods**

#### `resolve(query: string): Promise<QueryResult>`
Resolves a query with a definitive answer based on verifiable facts.
- Returns an answer that starts with "YES:", "NO:", or "AMBIGUOUS:"
- Used for past or current events
- Includes citation sources from Google Search grounding

#### `predict(query: string): Promise<QueryResult>`
Predicts the probability of a future event.
- Returns an answer starting with "PREDICTION: YES — X%" or "PREDICTION: NO — X%"
- Used for future events that haven't occurred yet
- Provides probabilistic forecasts based on current evidence
- Includes citation sources

#### `resolveAndPrepareTx({ ... }): Promise<ResolvedResult | NotResolvedResult>`
Resolves a query and either generates or broadcasts blockchain transaction data.
- Calls `resolve()` internally to get definitive answer
- Returns transaction data if resolved (YES/NO)
- Returns not_resolved status if outcome is ambiguous
- Can optionally broadcast the transaction to the blockchain

**Parameters:**
- `query`: The prediction query to resolve
- `abi`: Contract ABI as an array
- `contractAddress`: Smart contract address
- `functionName`: Function name to call
- `paramsBuilder`: Function that maps YES/NO to function parameters
- `chainRpc` (optional): RPC URL for broadcasting
- `privateKey` (optional): Private key for broadcasting

### Types

```typescript
interface QueryResult {
  answer: string;
  sources: Source[];
}

interface Source {
  uri: string;
  title: string;
}

// Resolved result (YES/NO)
interface ResolvedResult {
  status: 'resolved';
  answer: string;
  sources: Source[];
  to: string;
  data: string;
  txHash?: string; // Only present if transaction was broadcast
}

// Not resolved result (AMBIGUOUS)
interface NotResolvedResult {
  status: 'not_resolved';
  answer: string;
  sources: Source[];
}
```

## Features

- 🤖 AI-powered oracle using Gemini 2.5 Flash
- 🔍 Google Search grounding for factual information
- 📚 Automatic source citations
- ✅ Definite answers (YES/NO/AMBIGUOUS) via `resolve()`
- 📊 Probabilistic predictions via `predict()`
- ⛓️ Blockchain transaction preparation and broadcasting
- 🎯 Purpose-built for prediction market resolution
- 🔐 Supports transaction RD signature or broadcasting

## License

ISC