Ground SDKs

Ground provides official SDKs for TypeScript and Python. Both SDKs offer identical APIs and behavior, following Ground’s design philosophy of encoding correctness over convenience.

Installation

npm install @ground-ai/sdk

Quick Start

TypeScript
Python

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

const client = new GroundClient({
  apiKey: "gnd_your_api_key_here",
  baseUrl: "https://api.trygroundai.com"  // optional, defaults to this
});

// Search for context
const results = await client.search({
  query: "How to use tool_use with Claude API",
  max_tokens: 4000,
  top_k: 10
});

// Every result includes citations
for (const result of results.results) {
  console.log(result.content);
  console.log(`Source: ${result.citation.source_name}`);
  console.log(`Path: ${result.citation.path}`);
  console.log(`Stale: ${result.is_stale}`);
}

from ground_sdk import GroundClient, SearchRequest

client = GroundClient(
    api_key="gnd_your_api_key_here",
    base_url="https://api.trygroundai.com"  # optional
)

# Search for context
results = client.search(SearchRequest(
    query="How to use tool_use with Claude API",
    max_tokens=4000,
    top_k=10
))

# Every result includes citations
for result in results.results:
    print(result.content)
    print(f"Source: {result.citation.source_name}")
    print(f"Path: {result.citation.path}")
    print(f"Stale: {result.is_stale}")

Core Methods

Both SDKs expose the same methods:

Method	Description
`search()`	Hybrid search with citations
`createSource()`	Create a new source (repo, docs, or package)
`listSources()`	List all sources
`getSource()`	Get source by ID
`triggerSync()`	Start a sync job
`getJobStatus()`	Get job progress
`listJobs()`	List all jobs
`cancelJob()`	Cancel a running job

Design Philosophy

Ground SDKs encode correctness, not convenience:

What SDKs Do

Make the right thing easy
Make the wrong thing hard
Explicit parameters
No magical defaults
Surface trust metadata

What SDKs Don't Do

No ask() or answer generation
No automatic retries hiding failures
No opinionated agent wrappers
No agent loops

Error Handling

SDKs surface errors explicitly:

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

try {
  const results = await client.search({ query: "..." });
  
  // Check for warnings
  if (results.warnings.some(w => w instanceof StaleContextWarning)) {
    console.warn("Some results may be stale");
  }
} catch (error) {
  if (error instanceof NoEvidenceError) {
    console.log("No relevant context found");
  } else if (error instanceof AuthenticationError) {
    console.error("Invalid API key");
  }
}

SDKs

SDKs Overview

Ground SDKs

Installation

Quick Start

Core Methods

Design Philosophy

What SDKs Do

What SDKs Don't Do

Error Handling

Next Steps

TypeScript SDK

Python SDK

SDKs

​Ground SDKs

​Installation

​Quick Start

​Core Methods

​Design Philosophy

What SDKs Do

What SDKs Don't Do

​Error Handling

​Next Steps

TypeScript SDK

Python SDK

Ground SDKs

Installation

Quick Start

Core Methods

Design Philosophy

Error Handling

Next Steps