Skip to content
Back to search

customizable-gpt-chatbot

Veldra — talk an agent into existence, then watch it grow. A self-hostable, local-first agent platform: describe what you need in plain language and it compiles a working agent tools, MCP, RAG, teams. The more you use it, the better it gets agents learn from your feedback and reshape as you talk.

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/shamspias--customizable-gpt-chatbot/badge.svg)](/listings/shamspias--customizable-gpt-chatbot)

HTML

<a href="/listings/shamspias--customizable-gpt-chatbot"><img src="/api/listings/shamspias--customizable-gpt-chatbot/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.

Prereqs: **Docker** (and, for the local-first default, [Ollama](https://ollama.com)). One command checks prereqs, pulls the local models, creates `.env`, brings up the whole stack (Postgres+pgvector, Redis, MinIO, and the app), and waits for it to be healthy:

make quickstart

Then open **http://localhost:8000** → the **install wizard** walks you through it: name your workspace, test the provider connection, and create your admin account. Sign in and start building. `make down` stops everything, `make logs` tails the app.

<details><summary>Prefer to do it by hand?</summary>

ollama pull qwen3.5:0.8b          # agent model (tools + thinking)
ollama pull nomic-embed-text      # embeddings (768-dim)
make up                           # = docker compose -f deploy/docker-compose.yml up --build -d

</details>

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 · 243 lines

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

  1. <div align="center">
  2. # Veldra
  3. ### Talk an agent into existence.
  4. **A self-hostable, local-first agent-harness platform.** Describe what you need in
  5. plain language — Veldra compiles it into a *working agent*: its policy, tools,
  6. **skills**, a RAG knowledge base, a reasoning method, even a whole **team**. Route a
  7. task to the right agent automatically, connect external tools over **MCP**, and reshape
  8. anything later just by talking to it. Agents **learn from your feedback** and improve.
  9. ![status](https://img.shields.io/badge/status-MVP-5246e6)
  10. ![python](https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white)
  11. ![Vue](https://img.shields.io/badge/Vue-3-42b883?logo=vuedotjs&logoColor=white)
  12. ![FastAPI](https://img.shields.io/badge/FastAPI-009688?logo=fastapi&logoColor=white)
  13. ![Postgres](https://img.shields.io/badge/Postgres-pgvector-336791?logo=postgresql&logoColor=white)
  14. ![MCP](https://img.shields.io/badge/MCP-connectors-7c3aed)
  15. ![local-first](https://img.shields.io/badge/local--first-Ollama-000000)
  16. </div>
  17. ![Home dashboard](docs/screenshots/home.png)
  18. > **The one load-bearing idea:** an agent is *data*, not code — a versioned
  19. > `AgentSpec` row in Postgres. "Build me an agent" = compile natural language →
  20. > validated `AgentSpec`. "Change it" = a JSON-Patch you approve. The runtime is a
  21. > pure interpreter of that spec.
  22. ---
  23. ## ✨ Highlights
  24. - **Type a task — it routes or builds.** A smart composer auto-selects the best
  25. existing agent for what you typed, or builds a new agent from the prompt and drops
  26. you straight into its chat.
  27. - **A real workspace, with sign-in.** A first-run **install wizard** (name the
  28. workspace, check your providers, create the admin), then a sign-in gate. Invite
  29. teammates with roles — **admin / member / viewer**.
  30. - **Plugins & MCP connectors.** Built-in tools (calculator, web scraper, RAG search,
  31. HTTP, workspace files, …) are always on. Install external **MCP connectors**
  32. (Shopify, Alibaba, or any Streamable-HTTP / SSE / stdio server) from a template
  33. gallery — configure credentials, test the connection, enable per agent. Side-effecting
  34. connector tools require explicit approval.
  35. - **Agent teams.** Describe a business and the orchestrator plans a coordinator +
  36. specialists and wires them together (depth-capped delegation).
  37. - **Editable knowledge bases.** Upload PDFs/markdown or **index a web page**; edit a
  38. document and it re-embeds; per-KB **retrieval mode** (semantic / keyword / hybrid),
  39. **embedding model**, **reranker**, and **vector store** (pgvector / Qdrant). Citations
  40. carry `page` / `section` / `char-span`.
  41. - **A visual workflow builder.** start · end · llm · classifier · kb_search · if_else ·
  42. condition · code (sandboxed) · tool · http · template · aggregator — per-node inspector
  43. and typed variable passing.
  44. - **Agents with a soul.** Every agent has a *persona* — a character and voice (its
  45. "soul") that shapes how it talks, distinct from what it does. And it **grows little by
  46. little**: with auto-improve on, it reflects and stores a *lesson* not only from a 👎
  47. but quietly from its own mistakes (a failed tool call, a dead-end) — like a colleague
  48. who gets sharper the more they work with you. Lessons + persona are injected on every
  49. future run, so experience accumulates.
  50. - **Faust**, the floating admin bot: rename / tag / re-policy / delete agents, inspect &
  51. clear logs, manage documents — through audited admin tools.
  52. - **Insights & Activity** — usage / cost / reliability rollups and the full step trace
  53. of every build / ask / edit.
  54. ## 📸 Screenshots
  55. | | |
  56. |---|---|
  57. | ![Home](docs/screenshots/home.png) | ![All agents](docs/screenshots/agents.png) |
  58. | **Home** — smart composer, KPI strip, agent board | **All agents** — gallery, tags, chat / builder |
  59. | ![Plugins](docs/screenshots/plugins.png) | ![Setup](docs/screenshots/setup.png) |
  60. | **Plugins** — MCP connectors + template gallery | **Install wizard** — first-run setup |
  61. ## 🏗️ Architecture at a glance
  62. ```mermaid
  63. flowchart LR
  64. UI["Vue 3 SPA<br/>(workspace UI)"] -->|"REST + SSE (bearer)"| API["FastAPI edge"]
  65. API --> AUTH["Auth + install wizard<br/>users · roles · sessions"]
  66. API --> ORCH["Orchestrator<br/>NL → AgentSpec · route · self-mod"]
  67. API --> RT["Runtime<br/>native · decision loop · workflow"]
  68. RT --> REG["Tool registry<br/>builtins + plugin (MCP) tools"]
  69. REG -->|stdio · HTTP · SSE| MCP[("External MCP<br/>Shopify · Alibaba · …")]
  70. ORCH --> DB[("Postgres + pgvector")]
  71. RT --> DB
  72. AUTH --> DB
  73. RT --> LLM[("LLM provider<br/>Ollama · OpenAI · Anthropic")]
  74. RT --> S3[("MinIO / S3")]
  75. API --> REDIS[("Redis")]
  76. ```
  77. Everything is one FastAPI process (edge + orchestrator + runtime + RAG) plus the Vue
  78. SPA. An agent is a stable `agents` row + an append-only stack of immutable
  79. `AgentSpec` versions; the runtime is a pure interpreter of the current version.
  80. ## 🚀 Quick start — one command
  81. Prereqs: **Docker** (and, for the local-first default, [Ollama](https://ollama.com)).
  82. One command checks prereqs, pulls the local models, creates `.env`, brings up the whole
  83. stack (Postgres+pgvector, Redis, MinIO, and the app), and waits for it to be healthy:
  84. ```bash
  85. make quickstart
  86. ```
  87. Then open **http://localhost:8000** → the **install wizard** walks you through it: name
  88. your workspace, test the provider connection, and create your admin account. Sign in and
  89. start building. `make down` stops everything, `make logs` tails the app.
  90. <details><summary>Prefer to do it by hand?</summary>
  91. ```bash
  92. ollama pull qwen3.5:0.8b # agent model (tools + thinking)
  93. ollama pull nomic-embed-text # embeddings (768-dim)
  94. make up # = docker compose -f deploy/docker-compose.yml up --build -d
  95. ```
  96. </details>
  97. ## 🧑‍💻 Quick start — dev (hot reload)
  98. Prereqs: also [uv](https://docs.astral.sh/uv/) + Node 20.19+.
  99. ```bash
  100. cp example.env .env
  101. make dev # infra in Docker + migrate; prints the run commands
  102. uv run uvicorn veldra_app.main:app --reload # API on :8000
  103. cd apps/web && npm install && npm run dev # UI on :5173 (proxies /api → :8000)
  104. ```
  105. Then describe what you want (e.g. *"answer questions from these docs and always cite
  106. the page"*) — Veldra builds the agent and you chat with it. Or use the CLI (set
  107. `VELDRA_AUTH_ENABLED=false` for local, or `VELDRA_SERVICE_TOKEN`):
  108. ```bash
  109. uv run veldra kb add ./whitepaper.pdf
  110. uv run veldra build "answer from my docs with citations"
  111. uv run veldra ask "what does section 3 say about pricing?"
  112. ```
  113. ## 🧩 What you can build
  114. | Build this | How |
  115. |---|---|
  116. | **A single agent** | Type a task or a description — the orchestrator writes the policy, picks tools/skills/KB and a thinking method. |
  117. | **A whole team** | "Build a team to run an online store" → a coordinator + specialists, wired via `sub_agents`. |
  118. | **Tool-using agents** | Grant built-ins (`kb.search`, `calc.eval`, `web.scrape`, `http.fetch`, `time.now`, `fs.*`, `json.query`, `regex.extract`) or **plugin** tools from connected MCP servers. |
  119. | **Connected agents** | Install MCP connectors (Shopify, Alibaba, or any HTTP/SSE/stdio server); their tools appear in the catalog and the orchestrator can grant them. |
  120. | **RAG agents** | Attach an editable knowledge base; answers cite `page` / `section`. |
  121. | **Workflows** | A typed `workflow_graph` the runtime executes — author by asking or on the visual canvas. |
  122. | **Self-improving agents** | Turn on auto-improve; 👎 feedback → reflection → a stored lesson injected next time. |
  123. ## 🔌 Plugins & MCP connectors
  124. Built-in tools are always available. To give agents new powers, an **admin** opens
  125. **Plugins → Add connector** and picks a template:
  126. | Connector | Transport | Configure |
  127. |---|---|---|
  128. | **Shopify** | Streamable HTTP | server URL + access token |
  129. | **Alibaba** | Streamable HTTP | MCP endpoint + API key |
  130. | **Custom HTTP / SSE** | HTTP / SSE | any MCP server URL (+ optional headers) |
  131. | **Local (stdio)** | stdio | a command to run, e.g. `npx -y some-mcp-server` |
  132. Credentials are stored server-side and never returned to the browser. **Test
  133. connection** lists the server's tools; once enabled, they appear as `<key>.<tool>` in
  134. the catalog. A connector tool set to `permission_mode: ask` requires explicit approval
  135. before it runs.
  136. ## 🤖 Models / providers
  137. The LLM layer is **provider-pluggable** via `VELDRA_LLM_PROVIDER`:
  138. | Provider | value | Notes |
  139. |---|---|---|
  140. | **Ollama** (default) | `ollama` | Fully local, no key. `VELDRA_OLLAMA_MODEL` (+ optional `VELDRA_OLLAMA_ORCHESTRATOR_MODEL`). |
  141. | **OpenAI-compatible** | `openai` | OpenAI, Groq, OpenRouter, vLLM, LM Studio — set `VELDRA_OPENAI_BASE_URL`, `OPENAI_API_KEY`, `VELDRA_OPENAI_MODEL`. |
  142. | **Anthropic** | `anthropic` | Claude with adaptive thinking + `effort`. Needs `ANTHROPIC_API_KEY`. |
  143. Embeddings are independently pluggable (`VELDRA_EMBED_PROVIDER`): local Ollama
  144. `nomic-embed-text` (768-dim) by default, or OpenAI `text-embedding-3-small` (1536). The
  145. dimension is fixed at first migration.
  146. ### Agent loop modes (`VELDRA_AGENT_MODE`)
  147. To stay reliable even on **sub-1B local models**, `auto` runs a **constrained decision
  148. loop** for local/small models instead of fragile native tool-calling: each step the
  149. model picks an action from an enum and fills exactly that tool's args via structured
  150. output (goal-aware prompting, required-field fallback, a no-progress breaker, bounded
  151. repair, graceful step-limit fallback). The final answer is a separate, streamed,
  152. *grounded* composition. Claude/large models keep native tool-calling. Force either with
  153. `VELDRA_AGENT_MODE=decision|native`. A repeatable suite (`python -m evals.decision_loop.run`)
  154. asserts, on `qwen3.5:0.8b`: 100% answered, **0 hallucinated tools**, each tool called
  155. once with non-empty args, and RAG answers cited.
  156. ## 🔐 Auth & access
  157. Multi-user, single workspace. First run shows the install wizard; thereafter a sign-in
  158. gate. Sessions are opaque bearer tokens (stored only as a SHA-256 hash, revocable +
  159. expiring); passwords use PBKDF2-SHA256 (stdlib, no native deps). Roles:
  160. - **admin** — everything, plus team management + plugins + Faust.
  161. - **member** — build / chat / edit agents, KBs, skills.
  162. - **viewer** — read-only.
  163. Set `VELDRA_AUTH_ENABLED=false` to resolve every request to the default workspace as a
  164. system admin (CLI, evals, trusted local single-user dev). See `example.env`.
  165. ## 🗂️ Repository layout
  166. ```
  167. apps/web/ Vue 3 + Vite + Pinia + TS — the workspace front-end
  168. services/app/ one FastAPI process: edge (REST+SSE) · auth · orchestrator · runtime · rag
  169. packages/ spec-schema · llm-providers · mcp-client · mcp-servers · thinking-methods
  170. cli/ thin Typer client (veldra kb add | build | ask | agents | selfmod)
  171. deploy/ docker-compose (postgres+pgvector, redis, minio) + Alembic migrations
  172. evals/ nl_to_spec golden accuracy · decision_loop reliability suite
  173. docs/ ARCHITECTURE.md + screenshots/
  174. ```
  175. ## 🩺 Troubleshooting
  176. | Symptom | Fix |
  177. |---|---|
  178. | App can't reach Ollama from Docker | The container reaches your host at `host.docker.internal`; make sure Ollama is running and the models are pulled. |
  179. | `port 5432 already in use` | The Postgres container maps host port **5433** (to avoid clashing with a local Postgres). The app talks to it on the Docker network. |
  180. | Embedding dimension mismatch | `VELDRA_EMBED_DIM` is fixed at first migration. Use an embedder of the same dimension, or re-index (or use Qdrant for mixed dims). |
  181. | Stuck on the install wizard | It only shows when no users exist and `VELDRA_AUTH_ENABLED=true`. To bypass auth entirely, set it to `false`. |
  182. | CLI gets 401 | With auth on, set `VELDRA_AUTH_ENABLED=false` for local use, or send `VELDRA_SERVICE_TOKEN` as a bearer token. |
  183. | A connector shows "error" | Open **Plugins**, hit **Test** — the error from the MCP server is shown. Check the URL, credentials, and that the server is reachable. |
  184. ## 📖 Glossary
  185. - **AgentSpec** — the validated, versioned JSON that *is* an agent (policy, model,
  186. tools, skills, KBs, team, workflow).
  187. - **Skill** — a reusable Markdown playbook injected into an agent's instructions.
  188. - **Connector / Plugin** — an external MCP server whose tools an agent can use.
  189. - **Decision loop** — the constrained, structured-output agent loop for small models.
  190. - **Lesson** — episodic memory learned from feedback, injected on future runs.
  191. - **Faust** — the admin meta-agent that manages the workspace by chatting.
  192. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full design, the provider
  193. interface, and the roadmap. The previous Django GPT-3.5 chatbot is preserved on the
  194. `archive/v1-django` tag.

Ratings and comments

Sign in to rate this skill.

Sign in

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