#marianoguerra/exa

flowchart LR
  C["@exa.Client<br/>search · contents · answer"] -->|HttpRequest| T["&@exa.Transport"]
  T -->|HttpResponse| C
  T --> A["@exa_http.AsyncHttpTransport<br/>moonbitlang/async/http"]
  T --> M["@exa.MockTransport<br/>canned responses, no network"]
  A --> E["api.exa.ai"]

#Install

moon add marianoguerra/exa

import {
  "marianoguerra/exa",
  "marianoguerra/exa/async_http" @exa_http,
  "moonbitlang/async",
}

#Quick start

///|
async fn main {
  let client = @exa_http.client_from_env()
  let response = client.search(
    "papers on retrieval-augmented generation",
    num_results=5,
    category=Publication,
    contents=@exa.ContentsOptions::new(highlights=On),
  )
  for result in response.results {
    println(result.title.unwrap_or("(untitled)"))
    println("  \{result.url}")
  }
}

EXA_API_KEY=... moon run cmd/main --target native -- "your query"

#Calls

///|
test "content options serialise the way the API expects" {
  let compact : Json = @exa.ContentsOptions::new(text=On, highlights=On).to_json()
  inspect(
    compact.stringify(),
    content=(
      #|{"text":true,"highlights":true}
    ),
  )
  let detailed : Json = @exa.ContentsOptions::new(
    text=With(@exa.TextOptions::new(max_characters=2000, verbosity=Full)),
    summary=With(@exa.SummaryOptions::new(query="what do they sell")),
    max_age_hours=0,
  ).to_json()
  inspect(
    detailed.stringify(),
    content=(
      #|{"text":{"maxCharacters":2000,"verbosity":"full"},"summary":{"query":"what do they sell"},"maxAgeHours":0}
    ),
  )
}

#Errors

///|
let response = client.search(query) catch {
  @exa.Api(..) as error if error.is_rate_limited() => ... // back off and retry
  @exa.Api(status~, tag~, message~, request_id~) => ...
  @exa.Decode(message) => ...
}

#Testing without a network

///|
fn run_async(work : async () -> Unit noraise) -> Unit = "%async.run"

///|
fn[T] block_on(work : async () -> T) -> T raise {
  let outcome : Array[Result[T, Error]] = []
  run_async(async fn() noraise {
    outcome.push(Ok(work()) catch { error => Err(error) })
  })
  match outcome {
    [Ok(value)] => value
    [Err(error)] => raise error
    _ => abort("async work did not complete synchronously")
  }
}

///|
test "a search against a canned response" {
  let transport = @exa.MockTransport::json(
    (
      #|{
      #|  "requestId": "req-1",
      #|  "results": [{"url": "https://exa.ai", "title": "Exa"}],
      #|  "costDollars": {"total": 0.005}
      #|}
    ),
  )
  let client = @exa.Client::new(transport, "test-key")
  let response = block_on(async fn() {
    client.search("what is exa", num_results=1)
  })

  // what came back
  assert_eq(response.results[0].title, Some("Exa"))
  assert_eq(response.cost_dollars.unwrap().total, 0.005)

  // and what went out
  inspect(
    transport.last_body().unwrap().stringify(),
    content=(
      #|{"query":"what is exa","numResults":1}
    ),
  )
}

///|
test "an api error surfaces as ExaError::Api" {
  let transport = @exa.MockTransport::json(
    (
      #|{"requestId":"req-2","error":"Invalid API key","tag":"INVALID_API_KEY"}
    ),
    status=401,
  )
  let client = @exa.Client::new(transport, "wrong-key")
  let failed = try {
    let _ = block_on(async fn() { client.search("q") })
    false
  } catch {
    @exa.Api(..) as error => error.is_unauthorized()
    _ => false
  }
  assert_true(failed)
}

///|
test "response values can be built with new" {
  let untitled = @exa.SearchResult::new("https://example.com")
  assert_eq(untitled.title, None)
  let titled = @exa.SearchResult::new("https://exa.ai", title="Exa")
  assert_eq(titled.title, Some("Exa"))
  assert_eq(titled.id, "https://exa.ai") // defaults to the url
  let response = @exa.SearchResponse::new(
    results=[titled, untitled],
    cost_dollars=@exa.CostDollars::new(0.005),
  )
  assert_eq(response.results[1].title, None)
}

///|
test "response values can be built as literals" {
  let result : @exa.SearchResult = {
    url: "https://exa.ai",
    id: "https://exa.ai",
    title: Some("Exa"),
    published_date: None,
    author: None,
    image: None,
    favicon: None,
    text: None,
    summary: None,
    highlights: [],
    highlight_scores: [],
    subpages: [],
    extras: None,
    raw: Json::null(),
  }
  assert_eq(result, @exa.SearchResult::new("https://exa.ai", title="Exa"))
  assert_eq({ ..result, title: None, }.title, None)
}

#Backends

#Not covered yet

#License