DEV Community: Kyle Eaton

Semantic Code Search

Kyle Eaton — Tue, 27 May 2025 14:49:15 +0000

From Prompt to Product

We at Ducky.ai noticed a strange thing has happened in software development, we’re no longer writing code in the traditional sense. Instead, we describe what we want and ask the machine to write the first draft. Tools like GitHub Copilot, Cursor, Replit, and Devin have changed what it means to build. The keyboard isn’t gone, but it’s quieter. Developers are prompting, guiding, reviewing. Code appears in response to our intent.

This isn’t a distant future. It’s happening now. Describe a function in a comment and Copilot autocompletes it. Open a new file in Cursor and ask for a feature, and it drafts the architecture across files. The role of a developer is less that of a typist, but more akin to a curator or conductor.

But even the best AI tools come with hallucinations; they end up guessing when they should know. Unlike other AI applications, such as a customer support where agents can improvise around vague answers, coding doesn’t tolerate bluffing. The truth in software is explicit. Ask a coding agent to help you with session handling, and it might invent a helper function that doesn’t exist, when the correct one is already defined two files over.

> ✨Vibe coding✨ is more fun in a public Slack channel

This bottleneck is not in generation, but in awareness. A coding agent can write a brilliant one-liner and then immediately trip over your codebase because it doesn’t remember what it wrote, can’t find what it needs, and has no understanding of how your large codebase works.

This is where semantic code search comes in. It doesn’t just match strings. It finds meaning. Ask “Where are users authenticated?” and it retrieves the right files, even if those exact words never appear. Ask “How is billing handled?” and it surfaces the file with your invoice scheduler. It acts like memory or intuition, the kind of context a smart developer builds over weeks of immersion.

Let’s help the agent stop guessing and give it the context it needs. Traditionally, that would mean stitching together a pipeline of embedding models, chunking logic, and a vector database, just to get basic retrieval working. This is typically fragile and hard to maintain, but Ducky abstracts all of that. We can skip the plumbing, and get semantic code search working in minutes.

Semantic Code Search with Ducky AI

Making your codebase searchable shouldn’t require setting up a vector database or designing a custom pipeline. With Ducky, it takes one script and a few lines of setup.

Here’s how it works.

Step one

Let’s prepare each file into a structured document with metadata so we can use semantic search and apply metadata filters later if we need to narrow things down. Our document looks something like this

{
    "content": content, # code content
    "doc_id": f.relative_to(root), # unique identifier
    "title": f.name,
    "metadata": {
        "root": root,
        "full_path": f.as_posix(),
        "file_type": f.suffix,
    },
    "index_name": "code-memory", # data store
}

Step two

Ducky supports up to 100 documents in a single upload. If you're working with a larger codebase, you’ll want to split your documents into batches. This keeps indexing smooth and avoids hitting the upload limit.

for i in range(0, len(docs), batch_size):
    batch = docs[i : i + batch_size]
    ducky.documents.batch_index(documents=batch)

Step three

Now let’s get Ducky set up.

Create a Ducky AI account
Create a project and an index — in the example above, we used code-memory
Get your API key from the project settings
Install the Python SDK

pip install duckyai

Initialize the client with your API key

ducky = DuckyAI(api_key="DUCKYAI_API_KEY")

Now putting everything together in less than 50 lines of code

import sys
from pathlib import Path
from duckyai import DuckyAI
from typing import List

ducky = DuckyAI(api_key='DUCKYAI_API_KEY')

def prepare_documents(files: List[Path], root: str) -> List[dict]:
    """Prepare documents for indexing."""
    return [
        {
            "content": content,
            "doc_id": str(f.relative_to(root)).replace("/", "-").replace(".", "-"),
            "title": f.name,
            "metadata": {
                "root": root,
                "full_path": f.as_posix(),
                "file_type": f.suffix,
            },
            "index_name": "code-memory",
        }
        for f in files
        if (content := f.read_text())
    ]

def batch_index_documents(docs: List[dict], batch_size: int = 100):
    """Index documents in batches."""
    for i in range(0, len(docs), batch_size):
        print(
            f"INFO: Indexing batch {i // batch_size + 1} of {len(docs) // batch_size + 1}"
        )
        ducky.documents.batch_index(documents=docs[i : i + batch_size])

if __name__ == "__main__":
    if len(sys.argv) < 2:
        sys.exit("Usage: python ingest.py <repo_path>")

    directory = sys.argv[1]
    files = list(Path(directory).rglob("*.py"))
    print(f"Found {len(files)} Python files.")

    docs = prepare_documents(files, directory)
    print(f"INFO: Prepared {len(docs)} documents for indexing.")

    batch_index_documents(docs)

Step four

Once your documents are indexed, you can search across your codebase using natural language. You can do this directly in the developer dashboard or use the SDK to retrieve results in your application.
Here’s how to run a simple query with the Python client:

results = ducky.documents.retrieve(
    index_name="code-memory",
    query="how do we track customer usage?",
    top_k=5,
    rerank=True,
)

for doc in results.documents:
    print(doc.title)
    print(doc.metadata)

What’s Next

We’ve made the codebase fully searchable in under 50 lines of code. No infrastructure setup. No model tuning. Just a clean semantic layer that lets you ask real questions about your own code and get useful answers back.

This isn’t just about search. It’s about enabling better tools, tighter feedback loops, and assistants that actually understand the systems they’re working in. If you’re building with AI, retrieval is not a nice-to-have. It’s foundational.

Try it on your own codebase, or check out our other resources

📘 Documentation – for detailed setup, search tuning, and advanced features
🧑‍🍳 Cookbooks – for practical examples and quick-start guides

How to build a Legal Document Chat with OpenAI, Ducky.ai, Next.js and Browserless

Kyle Eaton — Fri, 16 May 2025 15:57:06 +0000

What if anyone could chat with a legal document instead of having to read the whole thing?

I wanted to create a tool where users could paste a link to a legal document and instantly start asking it questions like:

Who owns the content I create?" - Figma ToS
What happens if I violate these terms?" - Apple T&Cs

Today, Fineprint is live and working. It took surprisingly little time to build, thanks to Ducky.

The stack

Here’s the technology that powers Fineprint

Frontend | Next.js - React.js & TypeScript
Backend Scraping | Browserless (headless Chrome)
Semantic Search & Retrieval | Ducky.ai
Language Generation | OpenAI
Hosting | Vercel

How It Works (with some code)

Submitting a document to analyze & index

Step 1 - We first create an index name based on the url and then use Browserless to load and scrape the visible text from the page.

const processDocument = async (url: string) => {
  setIsProcessing(true)
  setError(null)

  const indexName = getIndexNameFromUrl(url)
  const content = await scrapeContent(url)

  // Index the document using the nextjs API (code in 2. below)
  const response = await fetch("/api/document", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      indexName,
      title: indexName,
      content,
      url
    })
  })

  if (!response.ok) throw new Error("Failed to index document")

  return { indexName }
}

Step 2 - A new index is created for each document and the extracted “fine print” is indexed using [Ducky.ai’s API]

(https://docs.ducky.ai/reference/indextext#/).
export async function POST(req: Request) {
  const { indexName, title, content, url } = await req.json()

  // First create the index
  await DuckyClient.createIndex(indexName)

  // Then index the document
  const result = await DuckyClient.indexDocument({
    indexName,
    title,
    content,
    url
  })

  return NextResponse.json(result)
}

...

export type DuckyIndexDocumentParams = {
  indexName: string
  title: string
  content: string
  url: string
  docId?: string
}

export class DuckyClient {
  static async createIndex(indexName: string) {
    const response = await fetch(`${DUCKY_API}/indexes`, {
      method: "POST",
      headers: {
        "x-api-key": DUCKY_API_KEY,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({ index_name: indexName })
    })

    if (!response.ok) {
      throw new Error(`Failed to create index: ${response.body}`)
    }

    return response.json()
  }

  static async indexDocument(params: DuckyIndexDocumentParams) {
    const response = await fetch(`${DUCKY_API}/documents/index-text`, {
      method: "POST",
      headers: {
        "x-api-key": DUCKY_API_KEY,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        index_name: params.indexName,
        title: params.title,
        content: params.content,
        url: params.url,
        doc_id: params.docId || ""
      })
    })

    if (!response.ok) {
      throw new Error(`Failed to index content: ${response.statusText}`)
    }

    return response.json()
  }
}

Users ask questions about the document

Step 1 - Fineprint retrieves relevant chunks of content from Ducky

const { indexName, question } = await req.json() // From UI

// First, get relevant chunks from Ducky
const duckyResponse = await DuckyClient.retrieve({
  indexName,
  query: question,
  alpha: 1,
  topK: 3 // Get top 3 chunks for better context
})

// Prepare context from chunks
const context = duckyResponse.chunks.map((chunk) => chunk.content).join("\n\n")

...

type DuckyRetrieveParams = {
  indexName: string
  query: string
  alpha?: number
  topK?: number
}

static async retrieve(params: DuckyRetrieveParams): Promise<DuckyRetrieveResponse> {
  const response = await fetch(`${DUCKY_API_BASE}/documents/retrieve`, {
    method: "POST",
    headers: {
      "x-api-key": DUCKY_API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      index_name: params.indexName,
      query: params.query,
      alpha: params.alpha || 1,
      top_k: params.topK || 1
    })
  })

  if (!response.ok) {
    throw new Error(`Failed to retrieve documents: ${response.statusText}`)
  }

  return response.json()
}

Step 2 - The uses OpenAI to synthesise a clear, natural response based on the context.

// Prepare the prompt for OpenAI based on context and question
const messages = [
  {
    role: "system",
    content:
      "You are a helpful assistant that answers questions about terms and conditions documents. " + 
      "Use the provided context to answer questions accurately and concisely."
  },
  {
    role: "user",
    content: `Context from the document:\n\n${context}\n\nQuestion: ${question}`
  }
]

const response = await fetch(OPENAI_API_URL, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${OPENAI_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "gpt-3.5-turbo",
    messages,
    temperature: 0.7,
    max_tokens: 500
  })
})

// Simplified without error handling for readability
return { answer: result.choices[0].message.content }

System Flow

Here’s a simple breakdown of how it all connects:

Why Ducky.ai?

Honestly, Ducky was a game changer for this project.

Simple indexing — I didn’t have to build any custom indexing/search engine.
Reliable retrieval — The API delivers semantically relevant context with minimal tuning.
Zero infra management — No hosting embeddings, no worrying about scale.

In a world where retrieval is often the hardest part of building an AI product, Ducky made it easy.

What’s Next

I’m excited to keep building on top of Fineprint:

Support PDFs and uploads (not just URLs)
Highlight referenced sections directly in the document view
Expand offering and categorise documents: include privacy policies, insurance docs, contracts etc.
More sophisticated multi-document search (e.g., compare terms between providers)

Final Thoughts: Anyone Can Build AI Tools Now

This project helped reinforce the idea that you don’t need a giant ML team to build something magical with AI.

With tools like Ducky, OpenAI and Next.js/Vercel, developers can prototype and launch powerful AI-powered tools incredibly quickly.

Fineprint was essentially a 1 day project — imagine what’s possible when we really push the boundaries.

If you’ve been thinking about building something with AI — this is your sign to start.

Try it yourself

Visit www.askfineprint.com
Learn more about Ducky