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

# Knowledge Agent

> Level 3 - RAG-powered agents with document ingestion, search, and knowledge-augmented generation

<Info>
  **Current Version**: v0.1.0
</Info>

The **Knowledge Agent** (Level 3) is a production-ready RAG (Retrieval-Augmented Generation) starter kit for building knowledge-powered AI agents. It provides complete document ingestion, intelligent chunking, hybrid search, and RAG-enabled query capabilities—everything needed to build agents that answer questions from your organization's documents and data.

<Tip>
  This repository can be used as a base template for creating your own application. Select `starter-knowledge-base-agent` as the **repository\_template** when provisioning a new repository via **[Self Service](/agentic-ai/getting-started/self-service)**.
</Tip>

<Card title="GitHub Repository" icon="github" href="https://github.com/bb-ecos-agbs/starter-knowledge-base-agent">
  View source code, releases, and issues
</Card>

## Why RAG for Banking?

Financial institutions manage vast repositories of policies, regulations, product documentation, and customer-facing content. RAG enables agents to provide accurate, source-cited answers from this knowledge—critical for compliance, trust, and customer experience.

**Common use cases:**

* Policy and compliance Q\&A
* Product information lookup
* Internal knowledge base assistants
* Document-grounded customer support

## What You'll Get

This starter provides a complete RAG pipeline with three core capabilities:

<CardGroup cols={3}>
  <Card title="Document Ingestion" icon="file-import">
    Load PDFs, text, markdown, and web pages with multiple chunking strategies (character, token, semantic, recursive).
  </Card>

  <Card title="Hybrid Search" icon="magnifying-glass">
    Semantic vector search, keyword full-text search, and hybrid search with optional reranking for improved relevance.
  </Card>

  <Card title="RAG Agent" icon="brain">
    Knowledge-augmented responses with source citations. Answers grounded in your documents.
  </Card>
</CardGroup>

This documentation explains two implementation approaches:

<CardGroup cols={2}>
  <Card title="Starter Kit Implementation" icon="code">
    The native implementation included in this repository—custom pipelines using raw SQL, embeddings API, and search logic.
  </Card>

  <Card title="Agno Framework Alternative" icon="cube">
    Expandable examples throughout each section showing how to achieve similar functionality using Agno's built-in knowledge base, readers, and search features.
  </Card>
</CardGroup>

## Prerequisites

* **Python 3.11+**: Managed via UV
* **UV Package Manager**: Modern Python package manager (replaces pip/poetry)
* **PostgreSQL 14+**: With [pgvector](https://github.com/pgvector/pgvector) extension for vector storage
* **Docker**: For running PostgreSQL locally

<Warning>
  **Database Required**: This starter requires PostgreSQL with the pgvector extension. Unlike other starters, you must set up a database before running the application.
</Warning>

## Quick Start

<Steps>
  <Step title="Clone and Install UV">
    ```bash theme={"system"}
    git clone https://github.com/bb-ecos-agbs/starter-knowledge-base-agent.git
    cd starter-knowledge-base-agent

    # Install UV (macOS)
    brew install uv

    # Install UV (Linux/WSL)
    curl -LsSf https://astral.sh/uv/install.sh | sh
    ```
  </Step>

  <Step title="Setup Environment">
    ```bash theme={"system"}
    # Create virtual environment
    uv venv --python 3.11
    source .venv/bin/activate  # macOS/Linux
    # or .venv\Scripts\activate  # Windows

    # Copy environment template
    cp env.template .env
    ```
  </Step>

  <Step title="Configure Credentials">
    Edit `.env` with required values:

    ```ini theme={"system"}
    # Required - Artifactory credentials (for bb-ai-sdk)
    export UV_INDEX_BACKBASE_USERNAME=your-email@backbase.com
    export UV_INDEX_BACKBASE_PASSWORD=your-artifactory-token

    # AI Gateway
    AI_GATEWAY_ENDPOINT=https://ai-gateway.backbase.cloud
    AI_GATEWAY_API_KEY=your-api-key

    # Database
    DB_HOST=localhost
    DB_PORT=5432
    DB_NAME=knowledge_base
    DB_USER=postgres
    DB_PASSWORD=postgres

    # Observability (Langfuse, Grafana, or OTLP — see BB AI SDK Observability)
    LANGFUSE_PUBLIC_KEY=pk-lf-...
    LANGFUSE_SECRET_KEY=sk-lf-...
    LANGFUSE_HOST=https://cloud.langfuse.com

    # Web Proxy (Required for local dev)
    HTTP_PROXY=http://webproxy.infra.backbase.cloud:8888
    HTTPS_PROXY=http://webproxy.infra.backbase.cloud:8888
    ```
  </Step>

  <Step title="Setup Database and Install Dependencies">
    Set up PostgreSQL with pgvector. See [Database Setup](#database-setup) for detailed instructions on provisioning via Azure or running locally with Docker.

    ```bash theme={"system"}
    # Export env vars and sync dependencies
    source .env && uv sync
    ```
  </Step>

  <Step title="Run the Server">
    ```bash theme={"system"}
    uv run python -m src.main
    ```

    The server runs at `http://localhost:8000`. Access the API documentation at `/docs`.
  </Step>
</Steps>

<Warning>
  **VPN and Web Proxy**: Required for local development. Configure Aviatrix VPN and web proxy settings. See **[Onboarding Guide](/agentic-ai/getting-started/onboarding)** for setup instructions.
</Warning>

## Database Setup

The starter uses PostgreSQL with pgvector for vector storage and similarity search. You have two options for provisioning the database:

<Tabs>
  <Tab title="Azure PostgreSQL (Production)">
    Use **Self Service** to provision a managed PostgreSQL instance on Azure. This is the recommended approach for production deployments and shared development environments.

    <Info>
      See **[Self Service](/agentic-ai/getting-started/self-service)** for instructions on requesting PostgreSQL with pgvector extension and managing infrastructure access.
    </Info>

    Once provisioned, configure your `.env` with the provided credentials:

    ```ini theme={"system"}
    DB_HOST=your-postgres-instance-host
    DB_PORT=5432
    DB_NAME=knowledge_base
    DB_USER=your-username
    DB_PASSWORD=your-password
    DB_SSLMODE=require
    ```
  </Tab>

  <Tab title="Docker (Local Development)">
    For local development and testing, run PostgreSQL with pgvector using Docker:

    ```bash theme={"system"}
    # Start PostgreSQL with pgvector
    docker run -d --name pgvector \
      -p 5432:5432 \
      -e POSTGRES_PASSWORD=postgres \
      -e POSTGRES_DB=knowledge_base \
      pgvector/pgvector:pg16
    ```

    Configure your `.env` for local connection:

    ```ini theme={"system"}
    DB_HOST=localhost
    DB_PORT=5432
    DB_NAME=knowledge_base
    DB_USER=postgres
    DB_PASSWORD=postgres
    ```

    <Warning>
      Docker setup is intended for local development only. For production deployments, use Azure PostgreSQL via Self Service.
    </Warning>
  </Tab>
</Tabs>

### Initialize Database

After configuring your database connection, run the setup script to create the required tables:

```bash theme={"system"}
# Initialize database tables
uv run python scripts/setup_db.py
```

This creates three normalized tables:

| Table        | Purpose                             |
| ------------ | ----------------------------------- |
| `documents`  | Source documents with metadata      |
| `chunks`     | Text chunks with token counts       |
| `embeddings` | Vector embeddings (1536 dimensions) |

### Database Management

```bash theme={"system"}
# Test connection
uv run python scripts/setup_db.py --test

# Check database status
uv run python scripts/setup_db.py --status

# Reset database (drop and recreate)
uv run python scripts/setup_db.py --reset
```

<Accordion title="Using Agno Framework for Database">
  Agno manages its own schema automatically via `PgVector`. To use the AI Gateway for embeddings:

  ```python theme={"system"}
  import os
  from agno.vectordb.pgvector import PgVector, SearchType
  from agno.knowledge.embedder.openai import OpenAIEmbedder

  # Configure embedder to use AI Gateway
  gateway_url = os.getenv("AI_GATEWAY_ENDPOINT")
  gateway_key = os.getenv("AI_GATEWAY_API_KEY")

  embedder = OpenAIEmbedder(
      id=model_id,
      dimensions=1536,
      api_key="dummy-key-auth-via-header", # This is just a placeholder so can keep this as it is
      base_url=f"{gateway_url}/deployments/{model_id}",
      request_params={
          "extra_headers": {
              "x-agent-id": agent_id,
              "api-key": gateway_key,
          },
          "extra_query": {
              "api-version": "2024-10-21",
          },
      },
  )

  # Create knowledge base with the embedder
  kb = PgVector(
      table_name="my_kb",
      db_url="postgresql://user:pass@localhost:5432/db",
      embedder=embedder,
      search_type=SearchType.hybrid,
  )
  kb.create()  # Creates table automatically
  ```

  See [Agno PgVector Documentation](https://docs.agno.com/integrations/vectordb/pgvector) for more details on PgVector and other supported vector stores.
</Accordion>

## Document Ingestion

Add documents to the knowledge base using CLI scripts or the REST API.

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    # Ingest a single file
    uv run python scripts/ingest.py --file ./data/samples/document.pdf

    # With specific chunking strategy
    uv run python scripts/ingest.py --file ./document.pdf --chunking semantic

    # Ingest a directory
    uv run python scripts/ingest.py --dir ./docs/

    # Ingest from URL
    uv run python scripts/ingest.py --url https://example.com/article

    # PDF with OCR (for scanned documents)
    uv run python scripts/ingest.py --file ./scanned.pdf --ocr
    ```
  </Tab>

  <Tab title="API">
    ```bash theme={"system"}
    # Upload a file
    curl -X POST http://localhost:8000/ingest \
      -F "file=@document.pdf" \
      -F "chunking_strategy=recursive"

    # Ingest from URL
    curl -X POST http://localhost:8000/ingest \
      -F "url=https://example.com/article" \
      -F "chunking_strategy=semantic"

    # Ingest raw text
    curl -X POST http://localhost:8000/ingest \
      -F "text=Your text content here..." \
      -F "title=My Document"
    ```
  </Tab>
</Tabs>

### Chunking Strategies

| Strategy      | Description                      | Best For             |
| ------------- | -------------------------------- | -------------------- |
| **character** | Fixed character-based splits     | Simple text          |
| **token**     | Token-aware splitting (tiktoken) | LLM-optimized chunks |
| **semantic**  | Sentence boundary splitting      | Preserving meaning   |
| **recursive** | Hierarchical splitting (default) | Structured documents |

### Supported File Formats

| Format   | Extensions            |
| -------- | --------------------- |
| PDF      | `.pdf`                |
| Text     | `.txt`                |
| Markdown | `.md`                 |
| Web URLs | `http://`, `https://` |

<Accordion title="Using Agno Framework for Ingestion">
  Agno provides built-in [Readers](https://docs.agno.com/basics/knowledge/readers/overview) that transform raw content from various sources into structured `Document` objects. Readers handle parsing, text extraction, and automatic chunking.

  ```python theme={"system"}
  from agno.knowledge.reader.pdf_reader import PDFReader

  # Configure reader with chunking
  reader = PDFReader(
      chunk=True,
      chunk_size=1000,
  )

  # Read and process document
  documents = reader.read("document.pdf")

  # Add to knowledge base
  kb.load(documents)
  ```

  Agno supports multiple reader types including PDF, CSV, Markdown, JSON, and web content. See [Agno Readers Documentation](https://docs.agno.com/basics/knowledge/readers/overview) for the full list of supported readers and configuration options.

  For chunking strategies, Agno supports document chunking, fixed-size chunking, semantic chunking, and agentic chunking. See [Agno Chunking Documentation](https://docs.agno.com/basics/knowledge/chunking) for details.
</Accordion>

## Search & Retrieval

Query the knowledge base with multiple search strategies.

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    # Hybrid search (default - combines semantic and keyword)
    uv run python scripts/search.py "What is attention?"

    # Semantic search only (vector similarity)
    uv run python scripts/search.py "transformer architecture" --strategy semantic

    # Keyword search only (full-text)
    uv run python scripts/search.py "neural network" --strategy keyword

    # With reranking for better quality
    uv run python scripts/search.py "attention mechanism" --rerank
    ```
  </Tab>

  <Tab title="API">
    ```bash theme={"system"}
    # Basic hybrid search
    curl -X POST http://localhost:8000/search \
      -H "Content-Type: application/json" \
      -d '{"query": "What is attention?"}'

    # Semantic search with reranking
    curl -X POST http://localhost:8000/search \
      -H "Content-Type: application/json" \
      -d '{"query": "attention mechanism", "strategy": "semantic", "rerank": true}'

    # Search within specific documents
    curl -X POST http://localhost:8000/search \
      -H "Content-Type: application/json" \
      -d '{"query": "neural networks", "document_ids": ["doc-uuid-1"]}'
    ```
  </Tab>
</Tabs>

### Search Strategies

| Strategy     | Description                                 | Best For                                    |
| ------------ | ------------------------------------------- | ------------------------------------------- |
| **Semantic** | Vector similarity using embeddings          | Conceptual queries, finding related content |
| **Keyword**  | Full-text search with PostgreSQL tsvector   | Exact terms, specific phrases               |
| **Hybrid**   | Combined semantic + keyword with RRF fusion | General use, best overall accuracy          |

### Reranking

Reranking improves search result quality by re-scoring retrieved documents. Two backends are supported:

| Backend                 | Latency     | Setup             | Best For                    |
| ----------------------- | ----------- | ----------------- | --------------------------- |
| **Cohere**              | \~100-300ms | Requires API keys | Production, high throughput |
| **Local Cross-Encoder** | \~1-5s      | No setup needed   | Development, testing        |

<Tip>
  For production deployments, configure Cohere reranking via `COHERE_RERANK_ENDPOINT` and `COHERE_RERANK_API_KEY` environment variables.
</Tip>

<Accordion title="Using Agno Framework for Search">
  Agno provides built-in search capabilities on the knowledge base with support for different search types.

  ```python theme={"system"}
  # Basic search
  results = kb.search("What is attention?", limit=10)
  for r in results:
      print(f"{r.score:.3f}: {r.content[:100]}...")
  ```

  Agno's `PgVector` supports multiple search types configured at initialization:

  ```python theme={"system"}
  from agno.vectordb.pgvector import PgVector, SearchType

  kb = PgVector(
      table_name="my_kb",
      db_url=db_url,
      embedder=embedder,
      search_type=SearchType.hybrid,  # Options: vector, keyword, hybrid
  )
  ```

  See [Agno Search & Retrieval](https://docs.agno.com/basics/knowledge/search-and-retrieval) for advanced search configuration and filtering options.
</Accordion>

## RAG Agent

The starter includes a RAG-enabled agent that searches the knowledge base to answer questions with source citations.

```bash theme={"system"}
curl -X POST http://localhost:8000/agent/crude \
  -H "Content-Type: application/json" \
  -d '{"query": "What is the attention mechanism?"}'
```

**Response with sources:**

```json theme={"system"}
{
  "query": "What is the attention mechanism?",
  "answer": "Based on the knowledge base, the attention mechanism is a component that allows models to focus on relevant parts of the input...",
  "sources": [
    {
      "title": "attention_is_all_you_need.pdf",
      "source": "/data/samples/attention_is_all_you_need.pdf",
      "snippet": "An attention function can be described as mapping a query and a set of key-value pairs to an output..."
    }
  ]
}
```

<Accordion title="Using Agno Framework for RAG Agent">
  Agno agents can automatically search the knowledge base when configured with knowledge:

  ```python theme={"system"}
  from agno.agent import Agent

  agent = Agent(
      model=model,
      knowledge=kb,
      search_knowledge=True,  # Automatic retrieval
  )
  response = agent.run("Explain transformers")
  ```

  When `search_knowledge=True`, the agent automatically queries the knowledge base for relevant context before generating a response. You can also configure the number of results to retrieve and filtering options.

  See [Agno Knowledge Getting Started](https://docs.agno.com/basics/knowledge/getting-started) for more details on integrating knowledge bases with agents.
</Accordion>

## API Reference

| Method   | Endpoint          | Description                           |
| -------- | ----------------- | ------------------------------------- |
| `GET`    | `/`               | Service status                        |
| `GET`    | `/health`         | Health check                          |
| `POST`   | `/ingest`         | Ingest documents (file, URL, or text) |
| `GET`    | `/documents`      | List all documents                    |
| `GET`    | `/documents/{id}` | Get document details                  |
| `DELETE` | `/documents/{id}` | Delete a document                     |
| `POST`   | `/search`         | Search the knowledge base             |
| `POST`   | `/agent/crude`    | RAG agent query                       |

Access interactive API documentation at:

* **Swagger UI**: `http://localhost:8000/docs`
* **ReDoc**: `http://localhost:8000/redoc`

## Project Structure

```text theme={"system"}
starter-knowledge-base-agent/
├── .github/                    # CI/CD workflows
├── scripts/
│   ├── setup_db.py             # Database setup
│   ├── ingest.py               # Ingestion CLI
│   └── search.py               # Search CLI
├── src/
│   ├── main.py                 # App entry point
│   ├── agents/                 # RAG agent implementation
│   │   ├── assistant.py        # Agent with knowledge base tool
│   │   └── tools/              # Knowledge base search tool
│   ├── api/                    # FastAPI routes and schemas
│   │   ├── app.py
│   │   ├── schemas.py
│   │   └── routers/            # Ingest, search, documents, agent
│   ├── config/                 # Configuration management
│   ├── ingestion/              # Document ingestion pipeline
│   │   ├── loaders/            # PDF, text, markdown, web loaders
│   │   ├── chunkers/           # Chunking strategies
│   │   ├── embeddings/         # Embedding generation
│   │   └── pipeline.py         # Ingestion orchestrator
│   ├── search/                 # Search pipeline
│   │   ├── semantic.py         # Vector similarity search
│   │   ├── keyword.py          # Full-text search
│   │   ├── hybrid.py           # RRF fusion
│   │   ├── rerankers/          # Cohere, cross-encoder
│   │   └── pipeline.py         # Search orchestrator
│   └── storage/                # Database repositories
│       ├── document.py
│       ├── chunk.py
│       └── embedding.py
├── tests/                      # Test suite
├── redteam.yaml                # Red teaming configuration
├── Dockerfile                  # Container definition
└── pyproject.toml              # Dependencies
```

## Observability

The starter integrates **`bb-ai-sdk`** observability—export to Langfuse, Grafana, or an OTLP endpoint depending on your environment variables.

* **Automatic Tracing**: Captures full traces for agent runs, search queries, and LLM calls.
* **Embedding Tracking**: Monitors embedding generation costs and latency.
* **Search Analytics**: Tracks search queries, strategies, and result quality.
* **Configuration**: Managed via `LANGFUSE_*` environment variables.

<Info>
  This starter uses **bb-ai-sdk** for observability (Langfuse, Grafana, or OTLP) and AI Gateway. See **[BB AI SDK Observability](/agentic-ai/bb-ai-sdk/observability)** for configuration and custom tracing.
</Info>

## Development

### Run Tests

```bash theme={"system"}
source .env && uv sync --extra dev
uv run pytest tests/ -v

# With coverage
uv run pytest tests/ -v --cov=src
```

### Build Docker Image

```bash theme={"system"}
docker build -t starter-knowledge-base-agent:local .
```

## CI/CD

Standard workflows are pre-configured in `.github/workflows`:

* **PR Checks**: Linting, testing, and validation.
* **Build & Publish**: Docker image creation on merge.
* **Release**: Automated versioning and release notes.

<Info>
  See **[CI/CD Workflows](/agentic-ai/ci-cd-workflows/overview)** for pipeline details.
</Info>

## Next Steps

* **[Create Your First Agent](/agentic-ai/getting-started/creating-first-agent)**: Deploy to a runtime
* **[Starter Agent](/agentic-ai/starter-kits/starter-agent)**: Start with basic agent patterns
* **[Multi-Agent](/agentic-ai/starter-kits/multi-agent)**: Build agent teams
* **[MCP Agent](/agentic-ai/starter-kits/mcp-starters)**: Integrate with MCP servers
* **[BB AI SDK](/agentic-ai/bb-ai-sdk/overview)**: AI Gateway and observability