Skip to content
Back to search

Alfred

Alfred: An open-source Data Assistant for domain adoption, powered by agent skills, semantic knowledge graphs and relational data.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/wagner-niklas--alfred/badge.svg)](/listings/wagner-niklas--alfred)

HTML

<a href="/listings/wagner-niklas--alfred"><img src="/api/listings/wagner-niklas--alfred/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install [Node.js](https://nodejs.org/en) and [Docker](https://docs.docker.com/engine/install/). Run afterwards in your terminal:

cd alfred-app
npm install

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 144 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Alfred
  2. [![Next.js](https://img.shields.io/badge/Assistant%20UI-black?logo=next.js&logoColor=white)](#)
  3. [![Vercel](https://img.shields.io/badge/Vercel%20AI%20SDK-%23000000.svg?logo=vercel&logoColor=white)](#)
  4. [![Databricks](https://img.shields.io/badge/Databricks-FF3621?logo=databricks&logoColor=fff)](#)
  5. [![Neo4J](https://img.shields.io/badge/Neo4j-008CC1?logo=neo4j&logoColor=white)](#)
  6. [![Claude](https://img.shields.io/badge/Agent%20Skills-D97757?logo=claude&logoColor=fff)](#)
  7. [![ChatGPT](https://custom-icon-badges.demolab.com/badge/OpenAI%20Compatible-74aa9c?logo=openai)](#)
  8. Say it. Query it. Own it.
  9. ![App](./demo/app.png)
  10. Open source is how data stays free. However, most production-grade text-to-sql assistants are **not open source** and expose only a narrow text box on top of a proprietary stack.
  11. Alfred addresses this by providing a research-first open-source application:
  12. - A **semantic knowledge graph** that makes the domain model and its relationships first-class and navigable.
  13. - A **persistent, multi-thread chat interface** built on Assistant UI.
  14. - A **single, well-defined persistence layer** for chat history that can be replaced with your own database.
  15. - A **pluggable model abstraction layer** that lets you seamlessly switch between providers (e.g., OpenAI, Azure, or local models like Ollama or LM-Studio).
  16. ## Features
  17. - **Help with your Knowledge Graph**: Generate your first knowledge graph in an UI and adapt it with domain entities
  18. - **Persistent Multi-Thread Chat** with
  19. **Pluggable Chat History**: Swap the default SQLite persistence for your own database by re-implementing a small set of functions in `lib/db.ts`
  20. - **Natural Language Queries**: Ask questions about your data plain language
  21. - **Tool-based Architecture**: Extensible system for adding custom data tools
  22. - **Microphone Input (Dictation)** (if supported by the browser) and **Image & File Attachments**
  23. - **Agent Skills**: Extend Alfred's capabilites by adding skills to the ```alfred-app/mnt/skills directory```.
  24. ## Technology Stack
  25. - **Frontend**: Next.js 16+ with React 19 and Assistant UI for pre-built conversational interface
  26. - **AI Engine**: Vercel AI SDK using Azure OpenAI
  27. - **Data Platforms**: Databricks SQL, Neo4j knowledge graph
  28. - **UI**: Radix UI components with Tailwind CSS
  29. ## Prerequisites
  30. - Node.js 18+
  31. - npm or pnpm
  32. ## Installation
  33. Install [Node.js](https://nodejs.org/en) and [Docker](https://docs.docker.com/engine/install/). Run afterwards in your terminal:
  34. ```bash
  35. cd alfred-app
  36. npm install
  37. ```
  38. ## Environment Setup for the Knowledge Store
  39. The .env file provides Alfred with credentials for chat, embeddings, and databases. Chat and embedding settings should be configured depending on the provider (Azure or OpenAI). Keep this file private and do not commit it to version control. See `.env.example` and create your `.env.local` within the alfred-app directory. Feel free to user the provider of your choice, from azure to ollama (openai compatible).
  40. ```
  41. # Run Alfred using openai-compatible model, e.g. ollama, lm-studio,...
  42. CHAT_PROVIDER=openai
  43. OPENAI_API_KEY=ollama
  44. OPENAI_BASE_URL=e.g. http://localhost:11434/v1/
  45. OPENAI_CHAT_MODEL= e.g. gpt-oss:20b
  46. # Or run Alfred using any azure deployment
  47. CHAT_PROVIDER=azure
  48. AZURE_OPENAI_BASE_URL=https://xxxxxxxx.com/openai/
  49. AZURE_OPENAI_API_VERSION=xxxx-xx-xx
  50. AZURE_OPENAI_CHAT_DEPLOYMENT=gpt-5.1
  51. ...
  52. # Databricks and Neo4j credentials
  53. ```
  54. ## Getting started from scratch
  55. If you want to try Alfred and you do not have a concrete Databricks dataset nor a knowledge graph, you can start first with the [Databricks Free Edition](https://www.databricks.com/learn/free-edition). Run the script `create_databricks_schema.ipynb` to get your first data into databricks. From databricks you get your credentials for your ```.env```:
  56. ``` bash
  57. DATABRICKS_HOST=....databricks.com
  58. DATABRICKS_TOKEN=your_personal_access_token
  59. DATABRICKS_WAREHOUSE_ID=your_warehouse_id
  60. DATABRICKS_CATALOG=your_databricks_catalog
  61. DATABRICKS_SCHEMA=your_databricks_schema
  62. ```
  63. Add then to your ```.env``` the (default) credentials for neo4j knowledge graph (the neo4j will be build in the next step):
  64. ``` bash
  65. NEO4J_BOLT_URL=bolt://localhost:7687
  66. NEO4J_USERNAME=neo4j
  67. NEO4J_PASSWORD=password
  68. ```
  69. Next, we build and run both alfred and neo4j community edition with docker. The Alfred app itself can run without access to the database or the graph.
  70. ```
  71. cd alfred-app
  72. docker compose build .
  73. # Start the service
  74. docker compose up
  75. ```
  76. If you run into package or native module issues (like better-sqlite3), rebuild without cache:
  77. ```
  78. docker compose build --no-cache
  79. ```
  80. Next, access the applications:
  81. - **Neo4j Browser:** [http://localhost:7474](http://localhost:7474)
  82. - **Alfred App:** [http://localhost:8081](http://localhost:8081)
  83. Finally, go to the settings page, click on **Reset knowledge graph database**. Nodes and edges for your graph will be generated from your choosen database schema. Now your Alfred, add domain infos and start asking questions.
  84. ## Configuring Databricks and Neo4j Tools
  85. Alfred exposes its main data access paths as **tools** under `lib/tools/`. These tools are wired into the assistant runtime via the Vercel AI SDK and Assistant UI so the model can call them directly.
  86. ## Using a Personal Database for Chat History
  87. Chat threads and messages are persisted through a single server-side abstraction in `lib/db.ts`. To swap the default SQLite database for your own (e.g. Postgres, MySQL, or a cloud database):
  88. 1. **Keep the public API stable**: Preserve the exported types and function signatures in `lib/db.ts` (`ThreadRecord`, `MessageRecord`, `getThreads`, `createThread`, `updateThread`, `deleteThread`, `getMessages`, `appendMessage`, `deleteMessagesByThreadId`).
  89. 2. **Replace the implementation**: Remove the `better-sqlite3` setup and SQL statements and reimplement these functions using your preferred database client (e.g. Prisma, Drizzle, pg, Sequelize) and schema.
  90. 3. **Stay server-only**: Ensure `lib/db.ts` is only imported from server-side code (API routes under `app/api/threads`), and configure your own connection options via environment variables as needed.
  91. No changes are required in the Assistant UI integration (`components/alfred/runtime-provider.tsx`); once `lib/db.ts` is wired to your database, chat history will automatically use your personal backend.
  92. ### Multi-User and Production Setups
  93. The default schema treats all threads as belonging to user using a browser based cookie, which is sufficient for local development. For real multi-user deployments, **derive a `userId` from auth** in your API routes (e.g. from a session/JWT) in production, or use a fixed `"local-dev"` value during development.
  94. ## Contributing & Extending Alfred
  95. We encourage researchers and practitioners to extend Alfred with their own innovations. Examples include:
  96. - **Custom Data Sources & Tools**: Connect additional databases or build domain-specific query and analysis tools
  97. - **Multi-Modal & Visualization Support**: Add document integration and richer visualizations for tool outputs and reasoning steps
  98. - **Conversation & Collaboration Features**: Improve long-term conversation memory, add follow-up suggestions, or enable shared analysis workspaces
  99. We welcome pull requests, suggestions, and discussions about how Alfred can better serve your research or practice needs.
  100. ## Acknowledgement
  101. Alfred grew out of ongoing research on AI-based data assistants. Alfred builds on the work of the open-source community, including Next.js, React, Vercel AI SDK, Neo4j, Databricks, Radix UI, and others.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.