npm install @ground-ai/sdk

import { GroundClient } from "@ground-ai/sdk";

const client = new GroundClient({
  apiKey: process.env.GROUND_API_KEY,
  baseUrl: "https://api.trygroundai.com",  // optional
  timeout: 30000  // optional, in milliseconds
});

const results = await client.search({
  query: "How do I authenticate users?",
  top_k: 10,
  max_tokens: 4000,
  source_ids: ["source-uuid-1", "source-uuid-2"],  // optional
  include_stale: false  // optional, default false
});

// Response structure
console.log(results.results.length);        // Number of results
console.log(results.evidence_quality);      // Confidence metrics
console.log(results.warnings);              // Stale/conflict warnings
console.log(results.conflicts);             // Detected conflicts

// Each result includes
for (const r of results.results) {
  console.log(r.content);                   // The actual content
  console.log(r.score);                     // Relevance score
  console.log(r.token_count);               // Token count
  console.log(r.is_stale);                  // Staleness flag
  console.log(r.citation.source_name);      // Source name
  console.log(r.citation.path);             // File path or URL
  console.log(r.citation.start_line);       // Start line (for code)
  console.log(r.citation.version_ref);      // Commit SHA or version
}

// Create a repository source
const repoSource = await client.createSource({
  name: "My Backend",
  source_type: "repo",
  url: "https://github.com/myorg/backend",
  branch: "main"
});

// Create a documentation source
const docsSource = await client.createSource({
  name: "Stripe API",
  source_type: "docs",
  docs_format: "openapi",
  url: "https://api.stripe.com/openapi.json"
});

// List sources
const sources = await client.listSources();

// Get a specific source
const source = await client.getSource("source-uuid");

// Delete a source
await client.deleteSource("source-uuid");

// Trigger a sync
const job = await client.triggerSync("source-uuid");

// Poll for completion
let status = await client.getJobStatus(job.id);
while (status.status === "running") {
  await new Promise(r => setTimeout(r, 2000));
  status = await client.getJobStatus(job.id);
}

console.log(`Completed: ${status.files_processed} files, ${status.chunks_created} chunks`);

// List all jobs
const jobs = await client.listJobs({ status: "running" });

// Cancel a job
await client.cancelJob(job.id);

import { 
  NoEvidenceError, 
  StaleContextWarning,
  AuthenticationError,
  RateLimitError,
  APIError 
} from "@ground-ai/sdk";

try {
  const results = await client.search({ query: "..." });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid or missing API key
  } else if (error instanceof RateLimitError) {
    // Rate limit exceeded, retry after error.retryAfter seconds
  } else if (error instanceof NoEvidenceError) {
    // No results found with sufficient confidence
  } else if (error instanceof APIError) {
    // General API error
    console.error(error.status, error.message);
  }
}

import type {
  SearchRequest,
  SearchResponse,
  SearchResult,
  Citation,
  Source,
  SourceCreate,
  Job,
  EvidenceQuality,
  Warning,
  Conflict
} from "@ground-ai/sdk";