Skip to content
Back to search

secure-ai-agent

Security-first AI operations agent: hybrid RAG with verified citations, a LangGraph agent with human approval, role-based tools, Row-Level Security and a pinned MCP server.

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/tomasghilino--secure-ai-agent/badge.svg)](/listings/tomasghilino--secure-ai-agent)

HTML

<a href="/listings/tomasghilino--secure-ai-agent"><img src="/api/listings/tomasghilino--secure-ai-agent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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 · 61 lines
  1. # secure-ai-agent
  2. An AI operations agent for a fictional industrial distributor, built security-first. It
  3. answers questions from company documents with verified citations, looks up business data
  4. through read-only tools, and never changes anything without a human approval.
  5. ## Highlights
  6. - **Hybrid RAG**: pgvector + PostgreSQL full-text search fused with Reciprocal Rank Fusion;
  7. answers cite document, version and page, and refuse when the evidence is missing.
  8. Measured on a labelled set of 47 questions ([results](docs/benchmarks/2026-11-19-rag-local.md)).
  9. - **LangGraph agent** with a bounded loop over 8 read-only tools (orders, tickets,
  10. invoices, suppliers, policies).
  11. - **Human in the loop**: the only write (a return authorization) pauses the run until a
  12. supervisor approves it; state is persisted in PostgreSQL.
  13. - **Security controls**: tenant isolation with Row-Level Security, role-based tool
  14. authorization (deny by default), separation of duties, an append-only audit log and a
  15. kill switch. See the [threat model](docs/security/THREAT_MODEL.md), mapped to the OWASP
  16. Top 10 for LLM, agentic and MCP applications.
  17. - **MCP server** (read-only, stdio) usable from any MCP client; the agent's MCP client
  18. pins tool definitions by hash.
  19. - **Async ingestion**: PDF upload → queue → idempotent worker (extraction, chunking,
  20. embeddings with a cache).
  21. ## Tech stack
  22. | Area | Tools |
  23. | --- | --- |
  24. | API | Python 3.12, FastAPI, Pydantic |
  25. | Data | PostgreSQL 17, pgvector (HNSW), full-text search, SQLAlchemy 2 (async), Alembic |
  26. | AI | LangChain, LangGraph, MCP Python SDK |
  27. | Models | Ollama locally (Qwen3 8B, Qwen3-Embedding); Amazon Bedrock for staging (Claude Haiku, Titan Embeddings V2) |
  28. | Infrastructure | Docker Compose, SQS API (ElasticMQ locally) |
  29. | Quality | pytest (unit, integration, real-model), ruff, mypy (strict), uv |
  30. ## Run it locally
  31. Requirements: Docker, [uv](https://docs.astral.sh/uv/) and GNU Make. Models default to
  32. offline fakes, so no GPU or cloud account is needed.
  33. ```bash
  34. make setup # install dependencies and create .env
  35. make up migrate seed # PostgreSQL + queue, schema, business data
  36. make data ingest # generate the sample PDFs and index them
  37. make ask q="How many days do I have to return a product?"
  38. make agent q="Can customer C-1006 return order SO-2026-0103?"
  39. make dev # full stack; API docs at http://localhost:8000/docs
  40. make check # lint, type check, unit tests
  41. ```
  42. Real local models (NVIDIA GPU, ~8 GB VRAM): run `make llm-pull`, then set
  43. `LLM_PROVIDER=ollama` and `EMBEDDING_PROVIDER=ollama` in `.env`. `make help` lists every
  44. command.
  45. ## Documentation
  46. - [Architecture](docs/architecture/ARCHITECTURE.md)
  47. - [Threat model and security roadmap](docs/security/THREAT_MODEL.md)
  48. - [Architecture decision records](docs/adr)
  49. - [RAG evaluation results](docs/benchmarks/2026-11-19-rag-local.md)
  50. - [Roadmap](docs/ROADMAP.md)

Ratings and comments

Sign in to rate this skill.

Sign in

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