Getting Started

Ducky is a fully managed retrieval system designed to accelerate development for Retrieval-Augmented Generation (RAG) applications. With an intuitive API and robust deployment infrastructure, Ducky lets you focus on building smarter applications without managing complex search infrastructure.

Why Use Ducky

Easy to use: No headaches, no complexity. We spend all our time thinking about good retrieval, so you don't have to.

Fully managed: No infrastructure headaches, no hosting concerns. Focus on building your application while we handle the search infrastructure.

Made for LLM agents: Purpose-built for Retrieval-Augmented Generation with APIs designed specifically for AI applications and agent workflows.

Installation

Install the SDK for your preferred language:

pip install duckyai

npm install duckyai-ts

Account Setup

Create an account at app.ducky.ai
Follow the getting started guide to create your first Project
Create an Index within your project (an Index is a collection of your data)
Generate an API key from the API keys page

Index Your First Document

Upload data to your index to start using Ducky's retrieval capabilities:

from duckyai import DuckyAI

ducky = DuckyAI(api_key="your-api-key")

ducky.documents.index(
    index_name="recipes",
    content="""
        Chocolate chip cookies are a classic American treat. 
        Mix butter, sugar, eggs, flour, and chocolate chips. 
        Bake at 375°F for 9-11 minutes until golden brown.
    """,
    doc_id="chocolate-chip-cookies",
    metadata={
        "category": "dessert",
        "prep_time": 15,
        "cook_time": 10,
        "difficulty": "easy"
    }
)

import { Ducky } from "duckyai-ts";

const ducky = new Ducky({
  apiKey: process.env.DUCKY_API_KEY ?? "",
});

await ducky.documents.index({
  indexName: "recipes",
  content: `
    Chocolate chip cookies are a classic American treat. 
    Mix butter, sugar, eggs, flour, and chocolate chips. 
    Bake at 375°F for 9-11 minutes until golden brown.
  `,
  docId: "chocolate-chip-cookies",
  metadata: {
    category: "dessert",
    prep_time: 15,
    cook_time: 10,
    difficulty: "easy"
  }
});

Make Your First Retrieval

Search your indexed documents with natural language queries:

results = ducky.documents.retrieve(
    index_name="recipes",
    query="how to bake cookies?",
    top_k=5,
    rerank=False
)

print(f"Found {len(results.documents)} relevant documents")
for doc in results.documents:
    print(f"Document: {doc.doc_id}")
    print(f"Content: {doc.content_chunks[0]}")

const results = await ducky.documents.retrieve({
  indexName: "recipes",
  query: "how to bake cookies?",
  topK: 5,
  rerank: false
});

console.log(`Found ${results.documents.length} relevant documents`);
results.documents.forEach(doc => {
  console.log(`Document: ${doc.docId}`);
  console.log(`Content: ${doc.contentChunks[0]}`);
});

Understanding Parameters

top_k: Number of results to return (1-100)
rerank: Enable second-stage reranking for improved relevance

Filter with Metadata

Use metadata to narrow search results based on specific criteria:

# Add more documents with different metadata
ducky.documents.index(
    index_name="recipes",
    content="Grilled salmon with lemon and herbs. Season and grill for 6-8 minutes per side.",
    doc_id="grilled-salmon",
    metadata={
        "category": "main-course",
        "prep_time": 10,
        "cook_time": 15,
        "difficulty": "medium"
    }
)

# Search for easy recipes only
easy_recipes = ducky.documents.retrieve(
    index_name="recipes",
    query="quick cooking ideas",
    top_k=5,
    metadata_filter={
        "difficulty": "easy",
        "prep_time": {"$lte": 20}  # 20 minutes or less prep time
    }
)

// Add more documents with different metadata
await ducky.documents.index({
  indexName: "recipes",
  content: "Grilled salmon with lemon and herbs. Season and grill for 6-8 minutes per side.",
  docId: "grilled-salmon",
  metadata: {
    category: "main-course",
    prep_time: 10,
    cook_time: 15,
    difficulty: "medium"
  }
});

// Search for easy recipes only
const easyRecipes = await ducky.documents.retrieve({
  indexName: "recipes",
  query: "quick cooking ideas",
  topK: 5,
  metadataFilter: {
    difficulty: "easy",
    prep_time: { "$lte": 20 }  // 20 minutes or less prep time
  }
});

Understanding Results

Ducky returns results in two formats:

documents: Complete document information grouped by doc_id
chunks: Individual content segments with their scores

Each result includes the document's content, metadata, and a relevance score to help you understand result quality.

Next Steps

Core Concepts: Learn about Projects, Indexes, and document management
Advanced Metadata: Master complex filtering and data organization
Document Scores: Understand how relevance scoring works
API Reference: Explore all available endpoints and parameters

🦆
Get in touch or see our roadmap if you need help