pip install ground-sdk

from ground_sdk import GroundClient

client = GroundClient(
    api_key=os.environ["GROUND_API_KEY"],
    base_url="https://api.trygroundai.com",  # optional
    timeout=30  # optional, in seconds
)

from ground_sdk import SearchRequest

results = client.search(SearchRequest(
    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
print(len(results.results))          # Number of results
print(results.evidence_quality)      # Confidence metrics
print(results.warnings)              # Stale/conflict warnings
print(results.conflicts)             # Detected conflicts

# Each result includes
for r in results.results:
    print(r.content)                 # The actual content
    print(r.score)                   # Relevance score
    print(r.token_count)             # Token count
    print(r.is_stale)                # Staleness flag
    print(r.citation.source_name)    # Source name
    print(r.citation.path)           # File path or URL
    print(r.citation.start_line)     # Start line (for code)
    print(r.citation.version_ref)    # Commit SHA or version

from ground_sdk import SearchRequest

deep = client.search_rmh(
    SearchRequest(query="Where is OAuth handled?", top_k=12, max_tokens=4000),
    max_rounds=2,
    expand_neighbors=True,
    secondary_search=True,
)
print(deep.get("rmh"))

from ground_sdk import SourceCreate

# Create a repository source
repo_source = client.create_source(SourceCreate(
    name="My Backend",
    source_type="repo",
    url="https://github.com/myorg/backend",
    branch="main"
))

# Create a documentation source
docs_source = client.create_source(SourceCreate(
    name="Stripe API",
    source_type="docs",
    docs_format="openapi",
    url="https://api.stripe.com/openapi.json"
))

# List sources
sources = client.list_sources()

# Get a specific source
source = client.get_source("source-uuid")

# Delete a source
client.delete_source("source-uuid")

import time

# Trigger a sync
job = client.trigger_sync("source-uuid")

# Poll for completion
status = client.get_job_status(job.id)
while status.status == "running":
    time.sleep(2)
    status = client.get_job_status(job.id)

print(f"Completed: {status.files_processed} files, {status.chunks_created} chunks")

# List all jobs
jobs = client.list_jobs(status="running")

# Cancel a job
client.cancel_job(job.id)

from ground_sdk import AsyncGroundClient, SearchRequest

async def main():
    client = AsyncGroundClient(api_key="gnd_...")
    
    results = await client.search(SearchRequest(
        query="How to authenticate?",
        top_k=10
    ))
    
    for r in results.results:
        print(r.content)

asyncio.run(main())

from ground_sdk.errors import (
    NoEvidenceError,
    StaleContextWarning,
    AuthenticationError,
    RateLimitError,
    APIError
)

try:
    results = client.search(SearchRequest(query="..."))
except AuthenticationError:
    # Invalid or missing API key
    pass
except RateLimitError as e:
    # Rate limit exceeded, retry after e.retry_after seconds
    pass
except NoEvidenceError:
    # No results found with sufficient confidence
    pass
except APIError as e:
    # General API error
    print(e.status, e.message)

from ground_sdk.types import (
    SearchRequest,
    SearchResponse,
    SearchResult,
    Citation,
    Source,
    SourceCreate,
    Job,
    EvidenceQuality,
    Warning,
    Conflict
)