#document-intel-agent-template-intermediate-tier
A step up from the POC tier: real per-user JWT auth, a choice between FAISS and ChromaDB for vector storage, and a SQLite-backed audit trail — without the full AWS Bedrock + OpenSearch + Azure AD SSO footprint of the advanced tier. 🔐📊
| Tier | Use it when... | Link |
|---|---|---|
| POC | You're prototyping or demoing. Single-user, no auth, minutes to first answer. | agent-template-document-intel-poc |
| Intermediate (this repo) | You have real users who need to be isolated from each other, want to compare FAISS vs. Chroma, and want an audit trail — but don't need enterprise SSO/compliance infra yet. | — |
| Advanced | You're deploying for a real team/organization: AWS Bedrock Knowledge Bases, OpenSearch, Azure AD SSO, full multi-tenancy. | agent-template-document-intel-advanced |
Move down to POC if this feels heavier than you need. Move up to advanced when you have multiple teams (not just multiple users) needing isolation, compliance/audit requirements beyond a SQLite log, or need SSO.
Developers who've outgrown the POC tier's single-user assumption — you have real user accounts now, you want to compare vector store backends before committing to one, and you want to see who asked/uploaded what.
| Section | Link |
|---|---|
| Overview | Overview |
| Repo Structure | Repo Structure |
| Features | Features |
| FAISS vs. ChromaDB | FAISS vs. ChromaDB |
| Setup | Setup |
| Usage | Usage |
| Working with AI Coding Agents | Working with AI Coding Agents |
| Creating a Good README | Creating a Good README |
| Contribution | Contribution |
| License | License |
Register a user, log in, upload documents, ask questions — all scoped to that user, with every action logged. Vector storage is pluggable: swap VECTOR_STORE=faiss or VECTOR_STORE=chroma in .env without touching code.
- src/api/client: Embeddings + LLM generation wrappers.
- src/api/routers:
/auth,/ingest,/query,/documents,/audit. - src/api/schemas: Pydantic request/response models.
- src/api/utils: Extraction, chunking, both vector store backends + factory, SQLite persistence, password hashing.
- src/api/middleware: JWT auth.
- src/api/exceptions: Error handling pattern.
- Per-user JWT auth (register/login), so documents and queries are actually isolated between users. 🔐
- Choose your vector store: FAISS or ChromaDB, one env var to switch — see the comparison below. 🔀
- Audit trail: every upload, query, login, and delete is logged with a timestamp and queryable via
/audit. 🧾 - Context-grounded answers with citations + relevance scores. 🎯
- Same embeddings/LLM provider flexibility as the POC tier (local/HF embeddings, OpenAI/Bedrock generation). 🧠
Both are implemented behind the same VectorStoreBase interface (src/api/utils/vector_store_base.py) — switching is a one-line .env change, not a code change.
| FAISS | ChromaDB | |
|---|---|---|
| Best for | Fast similarity search over a mostly-static corpus | A document set that changes often (frequent add/delete) |
| Metadata filtering | Manual (over-fetch + filter in Python) | Built-in where clauses |
| Persistence | Index file + JSON metadata sidecar you manage | Handled by Chroma's PersistentClient |
| Deletes | IndexIDMap.remove_ids — a bit more code, still supported |
Native collection.delete(where=...) |
| When it shines | You've measured it's faster for your corpus size and query pattern | You want less to think about and are still iterating on what you're storing |
Default for this tier is chroma — it's the lower-friction choice for most people still shaping their document set. Switch to faiss once you have a stable corpus and want to benchmark raw retrieval speed.
See setup.md.
See usage.md for the full register → login → ingest → query → audit flow.
#working-with-ai-coding-agents
See CLAUDE.md.
See good-readme.md.
See contributing.md.
MIT — see LICENSE.