# Knowledge Base RAG API

Query knowledge bases directly from your agent code to retrieve relevant documents and generate responses with citations.

## Overview

The Knowledge Base RAG API provides two functions for interacting with knowledge bases:

* **`retrieveFromKnowledgeBase`**: Retrieve relevant documents based on a query
* **`retrieveAndGenerateFromKnowledgeBase`**: Retrieve documents and generate a response with citations

Both functions support metadata filtering, result count control, and automatic agent/environment isolation.

### Default Knowledge Base Selection

The `knowledgeBaseId` parameter is **optional**. If omitted, the backend will:

* **Exactly 1 KB** for the agent → automatically use it
* **0 KBs** → throw an error prompting you to create a knowledge base
* **>1 KBs** → throw an error requiring you to pass `knowledgeBaseId` explicitly to disambiguate

This simplifies usage for agents with a single knowledge base.

> **Before you start:** Create a knowledge base and upload documents in the platform dashboard. For agents with multiple knowledge bases, copy the `knowledgeBaseId` to pass explicitly. See [Knowledge Bases](https://docs.minded.com/platform/knowledge-bases).

## retrieveFromKnowledgeBase

Retrieve relevant documents from a knowledge base.

### Function Signature

```typescript
retrieveFromKnowledgeBase(
  params: {
    knowledgeBaseId?: string;
    environment: string;
    query: string;
    numberOfResults?: number;
    filters?: KnowledgeBaseFilter;
  },
  timeoutMs?: number
): Promise<{
  retrievalResults: KnowledgeBaseRetrievalResult[];
  nextToken?: string;
}>
```

### Parameters

| Parameter                | Type                | Required | Description                                                                                                                    |
| ------------------------ | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `params.knowledgeBaseId` | string              |          | ID of the knowledge base to query. If omitted, backend auto-selects the KB if exactly one exists; errors if 0 or >1 KBs exist. |
| `params.environment`     | string              | ✓        | Environment (e.g., 'development', 'production')                                                                                |
| `params.query`           | string              | ✓        | Search query string                                                                                                            |
| `params.numberOfResults` | number              |          | Number of results to return (default: 5)                                                                                       |
| `params.filters`         | KnowledgeBaseFilter |          | Metadata filters for the query                                                                                                 |
| `timeoutMs`              | number              |          | Query timeout (default: 30000ms)                                                                                               |

### Return Value

Returns a Promise with:

* `retrievalResults`: Array of retrieval results, each containing:
  * `content.text`: Text content of the document chunk
  * `location.s3Location.uri`: URI of the source document
  * `metadata`: Associated metadata as key-value pairs
  * `score`: Relevance score (0-1)
* `nextToken`: Optional token for pagination

### Examples

**With explicit knowledgeBaseId:**

```typescript
import { retrieveFromKnowledgeBase } from '@minded-ai/mindedjs';

const results = await retrieveFromKnowledgeBase({
  knowledgeBaseId: 'kb-abc123',
  environment: 'production',
  query: 'How do I reset my password?',
  numberOfResults: 10,
  filters: {
    equals: { key: 'label1', value: 'dept:support' },
  },
});

for (const result of results.retrievalResults) {
  console.log(`Score: ${result.score}`);
  console.log(`Content: ${result.content.text}`);
  console.log(`Source: ${result.location.s3Location.uri}`);
}
```

## retrieveAndGenerateFromKnowledgeBase

Retrieve documents and generate a response using an LLM, with citations referencing source documents.

### Function Signature

```typescript
retrieveAndGenerateFromKnowledgeBase(
  params: {
    knowledgeBaseId?: string;
    environment: string;
    query: string;
    modelArn?: string;
    numberOfResults?: number;
    filters?: KnowledgeBaseFilter;
  },
  timeoutMs?: number
): Promise<{
  output: string | null;
  citations: KnowledgeBaseCitation[];
  sessionId?: string;
}>
```

### Parameters

| Parameter                | Type                | Required | Description                                                                                                                    |
| ------------------------ | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `params.knowledgeBaseId` | string              |          | ID of the knowledge base to query. If omitted, backend auto-selects the KB if exactly one exists; errors if 0 or >1 KBs exist. |
| `params.environment`     | string              | ✓        | Environment (e.g., 'development', 'production')                                                                                |
| `params.query`           | string              | ✓        | Search query string                                                                                                            |
| `params.modelArn`        | string              |          | Model ARN for generation (uses default if not specified)                                                                       |
| `params.numberOfResults` | number              |          | Number of documents to retrieve (default: 5)                                                                                   |
| `params.filters`         | KnowledgeBaseFilter |          | Metadata filters for the query                                                                                                 |
| `timeoutMs`              | number              |          | Query timeout (default: 60000ms)                                                                                               |

### Return Value

Returns a Promise with:

* `output`: Generated text response (null if no relevant documents found)
* `citations`: Array of citations, each containing:
  * `generatedResponsePart.textResponsePart.text`: The part of the response that cites this source
  * `generatedResponsePart.textResponsePart.span`: Start/end positions in the response
  * `retrievedReferences`: Array of source documents referenced
* `sessionId`: Optional session ID for conversation continuity

### Examples

**With explicit knowledgeBaseId:**

```typescript
import { retrieveAndGenerateFromKnowledgeBase } from '@minded-ai/mindedjs';

const result = await retrieveAndGenerateFromKnowledgeBase({
  knowledgeBaseId: 'kb-abc123',
  environment: 'production',
  query: 'Summarize the refund policy',
  numberOfResults: 5,
});

if (result.output) {
  console.log('Response:', result.output);

  // Process citations
  for (const citation of result.citations) {
    console.log('Cited text:', citation.generatedResponsePart.textResponsePart.text);

    for (const ref of citation.retrievedReferences) {
      console.log('  Source:', ref.location.s3Location.uri);
      console.log('  Content:', ref.content.text.substring(0, 100) + '...');
    }
  }
} else {
  console.log('No relevant documents found');
}
```

## Filtering

Both functions support metadata filters for precise document retrieval.

### Filter Types

```typescript
interface KnowledgeBaseFilter {
  equals?: { key: string; value: string };
  notEquals?: { key: string; value: string };
  greaterThan?: { key: string; value: string };
  lessThan?: { key: string; value: string };
  andAll?: KnowledgeBaseFilter[];
  orAll?: KnowledgeBaseFilter[];
}
```

### Filter Examples

```typescript
import { retrieveFromKnowledgeBase } from '@minded-ai/mindedjs';

// Filter by label1
const results = await retrieveFromKnowledgeBase({
  knowledgeBaseId: 'kb-abc123',
  environment: 'production',
  query: 'pricing information',
  filters: {
    equals: { key: 'label1', value: 'dept:sales' },
  },
});

// Combine multiple filters with andAll
const results2 = await retrieveFromKnowledgeBase({
  environment: 'production',
  query: 'pricing information',
  filters: {
    andAll: [
      { equals: { key: 'label1', value: 'dept:sales' } },
      { equals: { key: 'label2', value: 'lang:en' } }
    ],
  },
});
```