exa-hello-world

# Exa Hello World

## Overview
Minimal working examples demonstrating all core Exa search operations: basic search, search with contents, find similar, and get contents. Each example is runnable standalone.

## Prerequisites
- `exa-js` SDK installed (`npm install exa-js`)
- `EXA_API_KEY` environment variable set
- Node.js 18+ with ES module support

## Instructions

### Step 1: Basic Search (Metadata Only)
```typescript
import Exa from "exa-js";

const exa = new Exa(process.env.EXA_API_KEY);

// Basic search returns URLs, titles, and scores — no page content
const results = await exa.search("best practices for building RAG pipelines", {
  type: "auto",       // auto | neural | keyword | fast | instant
  numResults: 5,
});

for (const r of results.results) {
  console.log(`[${r.score.toFixed(2)}] ${r.title}`);
  console.log(`  ${r.url}`);
}
```

### Step 2: Search with Contents
```typescript
// searchAndContents returns text, highlights, and/or summary with each result
const results = await exa.searchAndContents(
  "how transformers work in large language models",
  {
    type: "neural",
    numResults: 3,
    text: { maxCharacters: 1000 },
    highlights: { maxCharacters: 500, query: "attention mechanism" },
    summary: { query: "explain transformers simply" },
  }
);

for (const r of results.results) {
  console.log(`## ${r.title}`);
  console.log(`URL: ${r.url}`);
  console.log(`Summary: ${r.summary}`);
  console.log(`Text preview: ${r.text?.substring(0, 200)}...`);
  console.log(`Highlights: ${r.highlights?.join(" | ")}`);
  console.log();
}
```

### Step 3: Find Similar Pages
```typescript
// findSimilar takes a URL and returns semantically similar pages
const similar = await exa.findSimilarAndContents(
  "https://arxiv.org/abs/2301.00234",
  {
    numResults: 5,
    text: { maxCharacters: 500 },
    excludeSourceDomain: true,
  }
);

console.log("Pages similar to the seed URL:");
for (const r of similar.results) {
  console.log(`  ${r.title} — ${r.url}`);
}
```

### Step 4: Get Contents for Known URLs
```typescript
// getContents retrieves page content for specific URLs
const contents = await exa.getContents(
  ["https://example.com/article-1", "https://example.com/article-2"],
  {
    text: { maxCharacters: 2000 },
    highlights: { maxCharacters: 500 },
    livecrawl: "preferred",
    livecrawlTimeout: 10000,
  }
);

for (const r of contents.results) {
  console.log(`${r.title}: ${r.text?.length} chars retrieved`);
}
```

## Output
- Working TypeScript file with Exa client initialization
- Search results printed to console with titles, URLs, and scores
- Content extraction (text, highlights, summary) demonstrated
- Similarity search results from a seed URL

## Error Handling
| Error | HTTP Code | Cause | Solution |
|-------|-----------|-------|----------|
| `INVALID_API_KEY` | 401 | API key missing or invalid | Check `EXA_API_KEY` env var |
| `INVALID_REQUEST_BODY` | 400 | Malformed parameters | Verify parameter types match SDK docs |
| `NO_MORE_CREDITS` | 402 | Account credits depleted | Top up at dashboard.exa.ai |
| `429 Too Many Requests` | 429 | Rate limit exceeded | Wait and retry; default is 10 QPS |
| Empty `results` array | 200 | Query too narrow or filters too strict | Broaden query or relax date/domain filters |

## Examples

### Complete Runnable Script
```typescript
import Exa from "exa-js";

const exa = new Exa(process.env.EXA_API_KEY);

async function main() {
  // 1. Search
  const search = await exa.search("AI safety research", { numResults: 3 });
  console.log(`Found ${search.results.length} results\n`);

  // 2. Search with contents
  const detailed = await exa.searchAndContents("AI safety research", {
    numResults: 2,
    text: true,
    highlights: { maxCharacters: 300 },
  });
  console.log("First result text length:", detailed.results[0]?.text?.length);

  // 3. Find similar
  if (search.results[0]) {
    const similar = await exa.findSimilar(search.results[0].url, {
      numResults: 3,
    });
    console.log("\nSimilar pages:", similar.results.map(r => r.title));
  }
}

main().catch(console.error);
```

## Resources
- [Exa Quickstart](https://docs.exa.ai/reference/quickstart)
- [Exa Search Reference](https://docs.exa.ai/reference/search)
- [Exa Cheat Sheet](https://docs.exa.ai/sdks/cheat-sheet)

## Next Steps
Proceed to `exa-core-workflow-a` for neural search patterns or `exa-sdk-patterns` for production-ready code.