> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trygroundai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDKs Overview

> Official SDKs for Ground - TypeScript and Python

# 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

<CodeGroup>
  ```bash npm theme={null}
  npm install @ground-ai/sdk
  ```

  ```bash yarn theme={null}
  yarn add @ground-ai/sdk
  ```

  ```bash pip theme={null}
  pip install ground-sdk
  ```
</CodeGroup>

## Quick Start

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    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}`);
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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}")
    ```
  </Tab>
</Tabs>

## 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:

<CardGroup cols={2}>
  <Card title="What SDKs Do" icon="check">
    * Make the right thing easy
    * Make the wrong thing hard
    * Explicit parameters
    * No magical defaults
    * Surface trust metadata
  </Card>

  <Card title="What SDKs Don't Do" icon="xmark">
    * No `ask()` or answer generation
    * No automatic retries hiding failures
    * No opinionated agent wrappers
    * No agent loops
  </Card>
</CardGroup>

## Error Handling

SDKs surface errors explicitly:

```typescript theme={null}
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");
  }
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="TypeScript SDK" icon="js" href="/sdks/typescript">
    Complete TypeScript SDK reference
  </Card>

  <Card title="Python SDK" icon="python" href="/sdks/python">
    Complete Python SDK reference
  </Card>
</CardGroup>