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

# Package Ingestion

> Index npm and PyPI packages for accurate dependency documentation

# 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

<Tabs>
  <Tab title="npm Package">
    ```bash theme={null}
    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"
        }
      }'
    ```
  </Tab>

  <Tab title="PyPI Package">
    ```bash theme={null}
    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"
        }
      }'
    ```
  </Tab>
</Tabs>

## Using SDKs

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

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

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

```json theme={null}
{
  "extra_metadata": {
    "ecosystem": "npm",
    "version": "4.17.21"  // Specific version instead of "latest"
  }
}
```

## Search Examples

After indexing packages, search returns accurate context:

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="Index Core Dependencies">
    Focus on packages your team actually uses. Don't index everything from npm.
  </Accordion>

  <Accordion title="Use Specific Versions">
    For production, pin to specific versions to avoid staleness issues.
  </Accordion>

  <Accordion title="Combine with Repo Sources">
    Index both your code AND your dependencies for complete context.
  </Accordion>

  <Accordion title="Regular Syncs">
    Set up scheduled syncs to keep package docs fresh.
  </Accordion>
</AccordionGroup>

## Limitations

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

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