Build Chatbase

The build, in order

1. 1

   Local foundation and data contract

   hideshow

   Create the runnable local foundation for a bounded support FAQ assistant with citations and a human handoff queue, including the real schema and acceptance fixture.

   1. 1.1Create and start the local application

      Run the venv command first, then stop and activate it before running the remaining commands. Use your OS instructions: Windows .venv\Scripts\activate.bat in cmd, or .venv\Scripts\Activate.ps1 in PowerShell; macOS/Linux source .venv/bin/activate. Then install the listed packages. Create app.py exposing app, load .env with python-dotenv, and add a /healthz route. Freeze tested dependency versions to requirements.txt. Create .env manually from .env.example; replace SECRET_KEY before launch.

      Files app.pyrequirements.txt.env.example.gitignore

      terminalcopy

      python -m venv .venv
      python -m pip install Flask Flask-WTF python-dotenv waitress tzdata
      python -m pip freeze > requirements.txt
      python -m flask --app app run --host 127.0.0.1

   2. 1.2Implement storage and seed the named fixture

      For database-backed state create schema.sql and db.py using this model: sources(id,title,url,text,hash,enabled); chunks(id,source_id,text,position); conversations(id,visitor_hash); messages(id,conversation_id,role,text); citations(message_id,chunk_id); handoffs(id,conversation_id,email,summary,state). Add the auxiliary relationships explicitly used in later phases; use stable ids, foreign keys, parameterized values and transactions. For canonical files use atomic replacement and hashes instead. Implement python manage.py init and python manage.py seed to create only synthetic data: Five supplied FAQ documents, an answerable return-policy question, an unknown question and a source containing hostile instructions. Re-running init must not erase data.

      Files schema.sqldb.pymanage.pyfixtures/README.md

      terminalcopy

      python manage.py init
      python manage.py seed

   3. 1.3Protect the local request boundary

      Install Flask-WTF CSRF protection for forms and same-origin fetches, validate Host and Origin against SITE_URL, bound inputs and escape output. Deliberately public intake endpoints get bounded validation and rate limits; signed provider webhooks use signature checks instead of browser CSRF tokens. All other admin routes stay local until product authentication exists. When a later phase tests viewer/member permissions, implement the users, hashed passwords, expiring server sessions and role checks in this foundation first; product mode must never use a fabricated identity from request input. Add error, empty, keyboard-focus and retry states now.

      Files app.pytemplates/base.htmltest/test_foundation.py

   4. 1.4Verify the selected local model

      Create providers/local_model.py with a POST /api/chat adapter using the configured local model and stream:false. Validate structured output, bound input/output, set a timeout and reject cloud models or non-loopback inference URLs. Add a probe that sends one harmless prompt and a test double for deterministic tests. Missing model setup must disable generation with a specific error while leaving editing usable.

      Files providers/local_model.pyscripts/model_probe.py

      terminalcopy

      python scripts/model_probe.py

   done when · tick each as it passes

   • The documented start command serves /healthz and the initial screen at http://127.0.0.1:5000.
   • Restarting preserves the seeded records or canonical files; running init again deletes nothing.
   • A cross-origin state-changing request to an admin route is refused.

   watch out

   • The Flask development server is for local development only. Loopback binding alone does not replace CSRF and origin validation.

   next phase
2. 2

   Controlled knowledge intake

   hideshow

   Controlled knowledge intake for Chatbase: Accept owner-uploaded TXT/Markdown and pasted text with provenance; split into bounded paragraphs and index locally.

   1. 2.1Accept owner-uploaded TXT/Markdown and pasted text with provenance; split into bounded paragraphs and index locally.

      Accept owner-uploaded TXT/Markdown and pasted text with provenance; split into bounded paragraphs and index locally.

      Files features/controlled_knowledge_intake.pytemplates/controlled_knowledge_intake.html

   2. 2.2Preview source content and allow enable/disable/delete; delete associated chunks when removing a source.

      Preview source content and allow enable/disable/delete; delete associated chunks when removing a source.

      Files features/controlled_knowledge_intake.py

   3. 2.3Exercise the acceptance fixture

      Use Five supplied FAQ documents, an answerable return-policy question, an unknown question and a source containing hostile instructions. Check: Reimporting an unchanged source does not duplicate chunks. Then check: Disabling a source removes it from subsequent retrieval. Add a focused regression for the failure case under test/ using a temporary database or folder and fake external services; also perform the visible workflow in a browser.

      Files test/test_controlled_knowledge_intake.py

      terminalcopy

      python -m unittest discover -s test

   done when · tick each as it passes

   • Reimporting an unchanged source does not duplicate chunks.
   • Disabling a source removes it from subsequent retrieval.

   watch out

   • No open-web crawler, document execution or automatic connector is included in this first version.

   next phase
3. 3

   Cited answers

   hideshow

   Cited answers for Chatbase: Retrieve matching passages with SQLite full-text search and supply only those passages to the local model.

   1. 3.1Retrieve matching passages with SQLite full-text search and supply only those passages to the local model.

      Retrieve matching passages with SQLite full-text search and supply only those passages to the local model.

      Files features/cited_answers.pytemplates/cited_answers.html

   2. 3.2Require source chunk ids in the answer, reject unknown ids and show an abstention when evidence is absent; render output as escaped text.

      Require source chunk ids in the answer, reject unknown ids and show an abstention when evidence is absent; render output as escaped text.

      Files features/cited_answers.py

   3. 3.3Exercise the acceptance fixture

      Use Five supplied FAQ documents, an answerable return-policy question, an unknown question and a source containing hostile instructions. Check: The return-policy answer cites an existing enabled chunk containing the policy. Then check: The unknown question produces an abstention, and hostile source instructions cannot trigger tools. Add a focused regression for the failure case under test/ using a temporary database or folder and fake external services; also perform the visible workflow in a browser.

      Files test/test_cited_answers.py

      terminalcopy

      python -m unittest discover -s test

   done when · tick each as it passes

   • The return-policy answer cites an existing enabled chunk containing the policy.
   • The unknown question produces an abstention, and hostile source instructions cannot trigger tools.

   watch out

   • A valid citation id alone does not prove entailment; keep an owner-reviewed answer evaluation set.

   next phase
4. 4

   Widget and handoff

   hideshow

   Widget and handoff for Chatbase: Build an iframe chat widget with bounded messages, signed conversation identity and explicit allowed embedding origins.

   1. 4.1Build an iframe chat widget with bounded messages, signed conversation identity and explicit allowed embedding origins.

      Build an iframe chat widget with bounded messages, signed conversation identity and explicit allowed embedding origins.

      Files features/widget_and_handoff.pytemplates/widget_and_handoff.html

   2. 4.2Offer a consented email/summary handoff form stored in an owner queue; provide conversation export and retention deletion.

      Offer a consented email/summary handoff form stored in an owner queue; provide conversation export and retention deletion.

      Files features/widget_and_handoff.py

   3. 4.3Exercise the acceptance fixture

      Use Five supplied FAQ documents, an answerable return-policy question, an unknown question and a source containing hostile instructions. Check: One signed visitor cannot read another conversation by changing its id. Then check: Requesting a person creates one handoff and does not invent an order lookup result. Add a focused regression for the failure case under test/ using a temporary database or folder and fake external services; also perform the visible workflow in a browser.

      Files test/test_widget_and_handoff.py

      terminalcopy

      python -m unittest discover -s test

   done when · tick each as it passes

   • One signed visitor cannot read another conversation by changing its id.
   • Requesting a person creates one handoff and does not invent an order lookup result.

   watch out

   • Voice, write actions, customer account tools and omnichannel support are excluded; this FAQ agent cannot change orders.

   next phase
5. 5

   Portable delivery and clean-start proof

   hideshow

   Finish the Chatbase replacement with a documented first-run path and a recoverable export.

   1. 5.1Write the user-facing runbook

      Document prerequisites, every configuration variable, data locations and the three domain workflows: Controlled knowledge intake; Cited answers; Widget and handoff. Include the exclusions, actual costs and source check date 2026-09-05. Commands shown earlier that reference project files are files the builder must implement before running them.

      Files README.md.env.example

   2. 5.2Create and rehearse a recoverable backup

      Use sqlite3.Connection.backup for the database in DATA_DIR and pause writers while taking the matching attachment snapshot. Keep schema version, hashes and a manifest for chatbase. Restore into a separate empty directory or isolated deployment, with all outbound actions and schedules disabled. Recreate this proof: Five supplied FAQ documents, an answerable return-policy question, an unknown question and a source containing hostile instructions. Compare ids/counts and open the result before recording the restore date. Never test a restore over the only live copy.

      Files OPERATIONS.mdscripts/backup.py

   3. 5.3Reproduce the first-run experience

      Use a new folder and only README instructions to reach the fixture outcome. Install from requirements.txt, initialize storage, run the tests and exercise the UI at 375px and 1280px; use keyboard-only controls and inspect browser errors. Record exactly what passed; do not mark unrun checks complete.

      Files README.mdverification.md

      terminalcopy

      python -m pip install -r requirements.txt
      python -m unittest discover -s test

   done when · tick each as it passes

   • A new folder reaches the documented fixture outcome using only README instructions.
   • A backup restored in isolation preserves the proof data and can be opened.

   watch out

   • Export without an import or restore rehearsal is not verified portability.