Package Ingestion

Ground can index packages from npm and PyPI registries, providing accurate documentation context for your dependencies.

Why Index Packages?

When AI assistants answer questions about libraries, they often:

Use outdated patterns from training data
Hallucinate function signatures
Provide incorrect usage examples

Ground solves this by indexing the actual package metadata including:

README documentation
Package description and keywords
Type definitions (when available)
Version-specific information

Supported Registries

Registry	Status	Content Indexed
npm	✅ Supported	README, package.json, types
PyPI	✅ Supported	README, metadata, description

Creating a Package Source

npm Package
PyPI Package

curl -X POST https://api.trygroundai.com/sources \
-H "Authorization: Bearer gnd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "lodash",
    "source_type": "package",
    "url": "lodash",
    "extra_metadata": {
      "ecosystem": "npm",
      "version": "latest"
    }
  }'

curl -X POST https://api.trygroundai.com/sources \
-H "Authorization: Bearer gnd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "FastAPI",
    "source_type": "package",
    "url": "fastapi",
    "extra_metadata": {
      "ecosystem": "pypi",
      "version": "latest"
    }
  }'

Using SDKs

TypeScript
Python

// Index an npm package
const source = await client.createSource({
  name: "axios",
  source_type: "package",
  url: "axios",
  extra_metadata: {
    ecosystem: "npm",
    version: "latest"
  }
});

// Trigger sync
const job = await client.triggerSync(source.id);

# Index a PyPI package
source = client.create_source(SourceCreate(
    name="requests",
    source_type="package",
    url="requests",
    extra_metadata={
        "ecosystem": "pypi",
        "version": "latest"
    }
))

# Trigger sync
job = client.trigger_sync(source.id)

What Gets Indexed

npm Packages

Content	Description
`README.md`	Full README content
`package.json`	Name, description, keywords, dependencies
Type definitions	If `types` or `typings` field exists

PyPI Packages

Content	Description
`README`	Long description from PyPI
Metadata	Summary, keywords, classifiers
Version info	Current version number

Version Pinning

You can index specific versions:

{
  "extra_metadata": {
    "ecosystem": "npm",
    "version": "4.17.21"  // Specific version instead of "latest"
  }
}

Search Examples

After indexing packages, search returns accurate context:

curl "https://api.trygroundai.com/search" \
  -H "Authorization: Bearer gnd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "lodash debounce function", "top_k": 5}'

Response includes:

README sections about debounce
Package description
Keywords and related utilities

Best Practices

Index Core Dependencies

Focus on packages your team actually uses. Don’t index everything from npm.

Use Specific Versions

For production, pin to specific versions to avoid staleness issues.

Combine with Repo Sources

Index both your code AND your dependencies for complete context.

Regular Syncs

Set up scheduled syncs to keep package docs fresh.

Limitations

Package ingestion currently focuses on documentation and metadata. Full source code indexing is not yet supported.

Source code files are not indexed (only documentation)
Private registries not yet supported
Scoped packages (@org/package) require URL encoding

Getting Started

Core Concepts

Guides

Package Ingestion

Package Ingestion

Why Index Packages?

Supported Registries

Creating a Package Source

Using SDKs

What Gets Indexed

npm Packages

PyPI Packages

Version Pinning

Search Examples

Best Practices

Limitations

​Package Ingestion

​Why Index Packages?

​Supported Registries

​Creating a Package Source

​Using SDKs

​What Gets Indexed

​npm Packages

​PyPI Packages

​Version Pinning

​Search Examples

​Best Practices

​Limitations

Package Ingestion

Why Index Packages?

Supported Registries

Creating a Package Source

Using SDKs

What Gets Indexed

npm Packages

PyPI Packages

Version Pinning

Search Examples

Best Practices

Limitations