A natural language interface for vector databases. Works on the browser. Query your data in plain English and get context-aware, conversational answers.
- Natural Language Queries: Ask questions about your data using everyday language.
- Conversational Context: The system remembers previous queries for follow-ups.
- Multiple AI Models: Supports OpenAI GPT and Google Gemini.
- Flexible Schema: Works with any vector database schema.
- Markdown Rendering: Answers are formatted for easy reading.
- Modern UI: Clean, full-screen interface.
Set these in your .env file (see env.example):
DATABASE_URL=...
QDRANT_URL=...
QDRANT_API_KEY=...
OPENAI_API_KEY=...
GEMINI_API_KEY=...Global API Keys: If you use API keys across multiple projects, set them in your shell:
# In ~/.zshrc or ~/.bashrc
export OPENAI_API_KEY="sk-your-global-key"
export GEMINI_API_KEY="your-global-gemini-key".env files.
Project-Specific Keys: If you need different keys per project, do not set them in your shell. Instead set the following in your .env or .env.local:
OPENAI_API_KEY=<your-openai-key>
GEMINI_API_KEY=<your-gemini-key>For custom data schemas, you can optionally set:
ENTITY_FIELD= # Main entity field (default: "name")
ENTITY_TYPE= # Plural label for entities (default: "entities")
ITEM_TYPE= # Label for individual items (default: "items")
FILENAME_FIELD= # Field for file names (default: "file_name")
URL_FIELD= # Field for URLs (default: "item_url")
DESCRIPTION_FIELD= # Field for descriptions (default: "description")ENTITY_FIELD=author
ENTITY_TYPE=authors
ITEM_TYPE=documents
FILENAME_FIELD=document_name
URL_FIELD=document_url
DESCRIPTION_FIELD=summaryENTITY_FIELD=brand
ENTITY_TYPE=brands
ITEM_TYPE=products
FILENAME_FIELD=product_image
URL_FIELD=product_url
DESCRIPTION_FIELD=product_descriptionENTITY_FIELD=author
ENTITY_TYPE=researchers
ITEM_TYPE=papers
FILENAME_FIELD=paper_title
URL_FIELD=paper_url
DESCRIPTION_FIELD=abstract-
Clone the repository
git clone https://github.com/effieklimi/ursiform.git cd ursiform -
Install dependencies
npm install
-
Set up environment variables
cp env.example .env # Edit .env with your API keys and database details # Set up Qdrant connection details # Optional: Configure field mappings for your data schema as described above
-
Run the development server
npm run dev
- Ask questions like:
- "How many [entities] are in my database?"
- "List some [entities] from [collection]"
- "Find [items] by [entity name]"
- "Which [entity] has the most [items]?"
- "Show me the top 5 [entities] by [item] count"
- "Describe my database"
- The system supports follow-up and context-aware queries.
Query the vector database using natural language.
Request:
{
"question": "Your question here",
"collection": "optional_collection_name",
"model": "gpt-4o-mini",
"context": {
"conversationHistory": [],
"lastEntity": "optional_last_entity",
"lastCollection": "optional_last_collection"
}
}Response:
{
"answer": "I found 1,247 unique artists in your collection...",
"query_type": "count",
"data": { "count": 1247, "artists": ["Artist 1", "Artist 2", ...] },
"execution_time_ms": 1250,
"context": { "conversationHistory": [...], "lastEntity": "...", ... }
}- Frontend: Next.js with TypeScript and Tailwind CSS
- App Directory:
/app- Next.js app router (pages, layouts, API routes) - Components:
/frontend/components- Reusable React components - Styles:
/frontend/styles- Global CSS and styling
- App Directory:
- Backend: Next.js API routes and server logic (organized in
/backenddirectory) - Vector Database: Qdrant
- AI: OpenAI GPT and Google Gemini
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
MIT License - see LICENSE file for details.
Built with ❤️ in London.
This project uses TRPC with Next.js App Directory (not Pages directory). The TRPC setup includes:
- Route Handler:
app/api/trpc/[trpc]/route.ts- Handles all TRPC requests using the fetch adapter - Context:
lib/trpc.ts- Provides both Pages and App directory context functions - Routers:
lib/routers/- Contains all TRPC procedure definitions
- Provider:
frontend/components/providers/trpc-provider.tsx- TRPC React Query provider - Layout: App directory layout automatically includes the TRPC provider
- Start the development server:
npm run dev - Visit
/test-trpcto test the TRPC integration - Or run the test script:
node test-trpc-endpoint.js
The TRPC setup has been migrated from Pages directory (pages/api/trpc/) to App directory (app/api/trpc/[trpc]/). The old pages directory handlers have been removed.
chat.getAll- Get all chatschat.getById({ id })- Get specific chat with messageschat.create({ title? })- Create new chatchat.updateTitle({ id, title })- Update chat titlechat.delete({ id })- Delete chatchat.getCount- Get total chat countmessage.*- Message-related procedures
- Node.js >= 18.18.0 (Next.js 15 requirement)
- npm or yarn
// ... existing code ...