customizable-gpt-chatbot

The one load-bearing idea: an agent is data, not code — a versioned AgentSpec row in Postgres. “Build me an agent” = compile natural language → validated AgentSpec. “Change it” = a JSON-Patch you approve. The runtime is a pure interpreter of that spec.

✨ Highlights

• Type a task — it routes or builds. A smart composer auto-selects the best existing agent for what you typed, or builds a new agent from the prompt and drops you straight into its chat.
• A real workspace, with sign-in. A first-run install wizard (name the workspace, check your providers, create the admin), then a sign-in gate. Invite teammates with roles — admin / member / viewer.
• Plugins & MCP connectors. Built-in tools (calculator, web scraper, RAG search, HTTP, workspace files, …) are always on. Install external MCP connectors (Shopify, Alibaba, or any Streamable-HTTP / SSE / stdio server) from a template gallery — configure credentials, test the connection, enable per agent. Side-effecting connector tools require explicit approval.
• Agent teams. Describe a business and the orchestrator plans a coordinator + specialists and wires them together (depth-capped delegation).
• Editable knowledge bases. Upload PDFs/markdown or index a web page; edit a document and it re-embeds; per-KB retrieval mode (semantic / keyword / hybrid), embedding model, reranker, and vector store (pgvector / Qdrant). Citations carry page / section / char-span.
• A visual workflow builder. start · end · llm · classifier · kb_search · if_else · condition · code (sandboxed) · tool · http · template · aggregator — per-node inspector and typed variable passing.
• Agents with a soul. Every agent has a persona — a character and voice (its “soul”) that shapes how it talks, distinct from what it does. And it grows little by little: with auto-improve on, it reflects and stores a lesson not only from a 👎 but quietly from its own mistakes (a failed tool call, a dead-end) — like a colleague who gets sharper the more they work with you. Lessons + persona are injected on every future run, so experience accumulates.
• Faust, the floating admin bot: rename / tag / re-policy / delete agents, inspect & clear logs, manage documents — through audited admin tools.
• Insights & Activity — usage / cost / reliability rollups and the full step trace of every build / ask / edit.

📸 Screenshots

Home — smart composer, KPI strip, agent board	All agents — gallery, tags, chat / builder
Plugins — MCP connectors + template gallery	Install wizard — first-run setup

🏗️ Architecture at a glance

Everything is one FastAPI process (edge + orchestrator + runtime + RAG) plus the Vue SPA. An agent is a stable agents row + an append-only stack of immutable AgentSpec versions; the runtime is a pure interpreter of the current version.

🚀 Quick start — one command

Prereqs: Docker (and, for the local-first default, Ollama). 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.

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

🧑‍💻 Quick start — dev (hot reload)

Prereqs: also uv + Node 20.19+.

cp example.env .env
make dev                          # infra in Docker + migrate; prints the run commands
uv run uvicorn veldra_app.main:app --reload      # API on :8000
cd apps/web && npm install && npm run dev        # UI on :5173 (proxies /api → :8000)

Then describe what you want (e.g. “answer questions from these docs and always cite the page”) — Veldra builds the agent and you chat with it. Or use the CLI (set VELDRA_AUTH_ENABLED=false for local, or VELDRA_SERVICE_TOKEN):

uv run veldra kb add ./whitepaper.pdf
uv run veldra build "answer from my docs with citations"
uv run veldra ask "what does section 3 say about pricing?"

🧩 What you can build

🔌 Plugins & MCP connectors

Built-in tools are always available. To give agents new powers, an admin opens Plugins → Add connector and picks a template:

Credentials are stored server-side and never returned to the browser. Test connection lists the server’s tools; once enabled, they appear as <key>.<tool> in the catalog. A connector tool set to permission_mode: ask requires explicit approval before it runs.

🤖 Models / providers

The LLM layer is provider-pluggable via VELDRA_LLM_PROVIDER:

Embeddings are independently pluggable (VELDRA_EMBED_PROVIDER): local Ollama nomic-embed-text (768-dim) by default, or OpenAI text-embedding-3-small (1536). The dimension is fixed at first migration.

Agent loop modes (VELDRA_AGENT_MODE)

To stay reliable even on sub-1B local models, auto runs a constrained decision loop for local/small models instead of fragile native tool-calling: each step the model picks an action from an enum and fills exactly that tool’s args via structured output (goal-aware prompting, required-field fallback, a no-progress breaker, bounded repair, graceful step-limit fallback). The final answer is a separate, streamed, grounded composition. Claude/large models keep native tool-calling. Force either with VELDRA_AGENT_MODE=decision|native. A repeatable suite (python -m evals.decision_loop.run) asserts, on qwen3.5:0.8b: 100% answered, 0 hallucinated tools, each tool called once with non-empty args, and RAG answers cited.

🔐 Auth & access

Multi-user, single workspace. First run shows the install wizard; thereafter a sign-in gate. Sessions are opaque bearer tokens (stored only as a SHA-256 hash, revocable + expiring); passwords use PBKDF2-SHA256 (stdlib, no native deps). Roles:

• admin — everything, plus team management + plugins + Faust.
• member — build / chat / edit agents, KBs, skills.
• viewer — read-only.

Set VELDRA_AUTH_ENABLED=false to resolve every request to the default workspace as a system admin (CLI, evals, trusted local single-user dev). See example.env.

🗂️ Repository layout

apps/web/        Vue 3 + Vite + Pinia + TS — the workspace front-end
services/app/    one FastAPI process: edge (REST+SSE) · auth · orchestrator · runtime · rag
packages/        spec-schema · llm-providers · mcp-client · mcp-servers · thinking-methods
cli/             thin Typer client (veldra kb add | build | ask | agents | selfmod)
deploy/          docker-compose (postgres+pgvector, redis, minio) + Alembic migrations
evals/           nl_to_spec golden accuracy · decision_loop reliability suite
docs/            ARCHITECTURE.md + screenshots/

🩺 Troubleshooting

📖 Glossary

• AgentSpec — the validated, versioned JSON that is an agent (policy, model, tools, skills, KBs, team, workflow).
• Skill — a reusable Markdown playbook injected into an agent’s instructions.
• Connector / Plugin — an external MCP server whose tools an agent can use.
• Decision loop — the constrained, structured-output agent loop for small models.
• Lesson — episodic memory learned from feedback, injected on future runs.
• Faust — the admin meta-agent that manages the workspace by chatting.

See docs/ARCHITECTURE.md for the full design, the provider interface, and the roadmap. The previous Django GPT-3.5 chatbot is preserved on the archive/v1-django tag.