Guides

Use with Cursor

Tips for building Aether apps with Cursor, Windsurf, and other AI code editors.

AI code editors are great at writing Aether integrations — the SDK is straightforward and the patterns are repetitive. Here's how to get the best results.

Just want to add Aether to a project?

For a focused on-ramp with a ready-to-paste Cursor rule, a manual fallback, and example builds, see Add Aether to a Cursor project. This page covers broader prompting tips.

Project setup

Start a new project and install the SDK:

Bash
mkdir my-aether-app && cd my-aether-app
pip install aether-ai anthropic

Set your API keys in the editor's environment. In Cursor, open the command palette and search for "Environment" or add them to a .env file in your project root:

text
AETHER_API_KEY=your-aether-key
ANTHROPIC_API_KEY=your-anthropic-key

Don't commit .env files

Add .env to your .gitignore so your API keys don't end up on GitHub.

Prompting your AI editor

When asking Cursor or Windsurf to write Aether code, be specific about what you want. Here are prompts that work well:

Loading documents

"Write a Python script that reads all .txt files from a ./docs folder and inserts each one into Aether using the AetherClient. Print how many documents were inserted."

"Add a function that takes a user question, searches Aether for the top 3 relevant results using client.retrieve(), and returns the matching content as a single string."

Building a full RAG pipeline

"Build a CLI chatbot that: 1) loads all markdown files from ./knowledge into Aether, 2) takes user questions in a loop, 3) retrieves relevant context from Aether, 4) sends the context + question to Claude using the Anthropic SDK, 5) prints the response."

Adding a web interface

"Wrap this chatbot in a Streamlit app with a text input for questions and a chat-style display for answers. Keep using Aether for retrieval and Claude for generation."

Cursor rules for Aether projects

If you use Cursor, you can add a .cursorrules file to your project root to give the AI context about Aether:

text
This project uses the Aether SDK for document storage and vector search.

Key patterns:
- Use AetherClient() to create a client (reads AETHER_API_KEY from env automatically)
- client.insert_text("text") to store text documents
- client.insert(file_path="path.pdf", content_type="application/pdf") for files
- client.search("query", k=5) for semantic search (returns doc_id + score + passage)
- client.retrieve("query", k=5) for search + content (returns content field)
- Higher score = better match. Validate any cutoff against your own data.

RAG pattern:
1. Insert documents into Aether
2. Retrieve relevant chunks with client.retrieve()
3. Pass chunks as context to an LLM (Claude, GPT-4o, etc.)
4. The LLM answers based on the retrieved context

The Aether Python SDK is installed as: pip install aether-ai
The import is: from aether import AetherClient

This helps the AI editor generate correct Aether code on the first try instead of guessing the API.

Common patterns to ask for

Here are things you can ask your AI editor to build, and they'll work well with Aether:

Ask for...What it does
"Document ingestion script"Reads files from a folder and loads them into Aether
"Search API endpoint"Flask/FastAPI route that takes a query and returns Aether results
"RAG chatbot"Chat loop that retrieves context from Aether and generates answers
"Streamlit RAG app"Web UI for asking questions over your documents
"Slack bot with RAG"Bot that answers questions in Slack using your Aether knowledge base
"Document upload form"Web form that accepts file uploads and inserts them into Aether

Debugging tips

If the AI editor generates code that doesn't work:

  • "AetherClient not found" — Make sure aether-ai is installed (pip install aether-ai). The package name is aether-ai; the import name is aether.
  • "401 Unauthorized" — Your AETHER_API_KEY isn't set. Check your .env file or terminal.
  • Search returns nothing — You need to insert documents first. Search only works on documents you've already stored.
  • Results seem irrelevant — Try increasing k (number of results) or rewording the query. Aether searches by meaning, so try describing what you want differently.

Next steps