awesome-ai-apps Documentation

A collection of projects showcasing RAG, agents, workflows, and other AI use cases

16,463 stars Python Python 6 files · ~13,187 tokens #agents#ai#hacktoberfest#llm#mcp
RAW Doc

Technical Documentation: Arindam200/awesome-ai-apps

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (README.md)

This repository is a comprehensive collection of 132 projects, tutorials, and recipes for building powerful LLM-powered applications, including text agents, voice assistants, RAG apps, and MCP-backed tools. These projects serve as a guide for developers working with various AI frameworks and stacks.

📋 Table of Contents

🧩 Starter Agents

Quick-start agents for learning and extending different AI frameworks. 21 projects

🪶 Simple Agents

Straightforward, practical use-cases for everyday AI applications. 19 projects

🎙️ Voice Agents

Real-time voice assistants and streaming speech pipelines — including LiveKit, Pipecat, Gradium, and VoxCode (Deepgram + Cursor SDK). 9 projects

🗂️ MCP Agents

Examples using Model Context Protocol for external tool integration. 14 projects

🧠 Memory Agents

Agents with advanced memory capabilities for context retention and personalization. 13 projects

📚 RAG Applications

Retrieval-augmented generation examples for document understanding and knowledge bases. 18 projects

🔬 Advanced Agents

Complex multi-agent pipelines for production-ready end-to-end workflows. 35 projects

🧬 Fine-Tuning

End-to-end examples of fine-tuning open-source LLMs, from data prep to deployment. 6 projects

📺 Tutorials & Videos

🎓 Course Playlists

🔧 Framework Tutorials

Getting Started

Prerequisites

  • Python 3.10+ (Python 3.11+ recommended for newer projects)
  • Git for cloning the repository
  • Package Manager: pip or uv (recommended for faster installs)
  • API Keys: Most projects require API keys (see individual project READMEs)

Quick Start

  1. Clone the repository

    bash
    git clone https://github.com/Arindam200/awesome-ai-apps.git
cd awesome-ai-apps

  2. Choose a project and navigate to its directory

    bash
    cd starter_ai_agents/agno_starter  # Example: Start with Agno starter

  3. Set up environment variables

    bash
    cp .env.example .env  # Copy example environment file
# Edit .env with your API keys

  4. Install dependencies

    bash
    # Using pip
pip install -r requirements.txt

# OR using uv (recommended - faster)
uv sync
# or
uv pip install -e .

  5. Run the project

    bash
    python main.py
# or for Streamlit apps
streamlit run app.py

🤝 Contributing

We welcome contributions from the community! Here's how you can help:

  • 💡 Add new projects: Submit your own AI agent examples
  • 🔧 Fix issues: Contribute code improvements and bug fixes
  • 📝 Improve documentation: Help make projects more accessible
  • 🐛 Report bugs or suggest improvements via GitHub Issues

Before contributing:

  • Read our Contributing Guidelines for detailed information
  • Check existing issues to avoid duplicates
  • Follow the project structure and naming conventions
  • Ensure your project includes a comprehensive README.md

Important: This project follows a Contributor Code of Conduct. By participating, you agree to abide by its terms.

📜 License

This repository is licensed under the MIT License. Feel free to use and modify the examples for your projects.

👥 Core Maintainers

This project is actively maintained by:

For any questions, suggestions, or contributions, feel free to reach out to the maintainers.

Thank You for the Support! 🙏

Mcp Ai Agents Mcp Toolbox Security Agent Docs ARCHITECTURE (`mcp_ai_agents/mcp_toolbox_security_agent/docs/ARCHITECTURE.md`)

Architecture

Components

Component Role
agent-web (FastAPI + Google ADK) The user-facing app + shopping agent. The LLM is pluggable — Nebius Token Factory (Kimi-K2.6) by default via ADK's LiteLLM adapter, or Gemini (AGENT_PROVIDER=gemini). Loads Toolbox tools via the toolbox-core SDK. Lives outside the trust boundary, so the provider choice changes no security property. Gemini is still used for query embeddings (semantic search).
MCP Toolbox The security control plane. Serves curated tools over HTTP/MCP; binds identity from tokens; holds the DB credentials; emits OpenTelemetry.
PostgreSQL System of record: users, product catalog (price/stock), carts, orders. Accessed only via least-privilege roles.
MongoDB (Atlas Local) Vector/semantic product search over pre-computed Gemini embeddings ($vectorSearch).
Keycloak OIDC identity provider (local). Issues the JWTs Toolbox validates. Swapped for Google Sign-In in production.
OTel Collector + Jaeger Traces/metrics pipeline.

The trust boundary

text
┌─────────────────────────────────────┐
 login  │  agent-web (FastAPI)                 │
 alice  │  ├─ Google ADK + Gemini agent        │   tool calls (HTTP/MCP)
 bob    │  └─ deterministic demo endpoints     │──────────────┐
 carol  └──────────────┬──────────────────────┘   keycloak_token (JWT)
                       │ embeddings (Gemini)                   │
                       ▼                                       ▼
                 google-genai                       ╔════════════════════╗
                                                     ║   MCP  TOOLBOX     ║  ◀── TRUST BOUNDARY
   Keycloak (OIDC) ──issues JWT──────────────────▶  ║  • custom tools     ║
        ▲                                            ║  • authN params     ║
        └── agent-web logs users in (server-side)    ║  • authRequired     ║
                                                     ║  • parameterized    ║
                                                     ║  • least-priv roles ║
                                                     ╚═══╤═══════════╤═════╝
                                  parameterized SQL ($1) │           │ $vectorSearch
                                   role: toolbox_app/admin▼           ▼
                                              ┌───────────┐     ┌──────────┐
                                              │ PostgreSQL│     │ MongoDB  │
                                              └───────────┘     └──────────┘

Everything to the left of the double line is untrusted with respect to the
data: the LLM, its prompt, and the tool arguments it produces. All enforcement
happens at Toolbox and in the database.

Request lifecycle (e.g. "show my orders")

  1. The browser calls agent-web; the server attaches the signed-in user's JWT.
  2. The agent (or a deterministic endpoint) calls the Toolbox tool list_my_orders.
    The token travels in the keycloak_token header. No username is sent —
    the tool's schema doesn't have one.
  3. Toolbox validates the JWT against the OIDC issuer (signature, issuer,
    audience), extracts preferred_username, and binds it into the SQL parameter.
  4. Toolbox runs ... WHERE u.username = $1 as the least-privilege toolbox_app
    role, returns rows, and records a trace span.
  5. A different user's data is unreachable: the model can't pass username, and
    even a forged body value is ignored (the claim wins).

Why polyglot (Postgres + Mongo)

Transactional integrity (orders, carts, prices, least-privilege roles, IAM) lives
in PostgreSQL; semantic search lives in MongoDB vector search. Toolbox presents
one secure gateway over both, joined by sku. This shows the control plane
generalizing across very different datastores — a realistic production shape.

Local vs. GKE

Concern Local (compose) GKE (deploy/k8s/)
Postgres source kind: postgres + password kind: cloud-sql-postgres, no password (IAM)
DB auth role password in .env Workload Identity KSA→GSA, IAM DB users
tools.yaml bind-mounted file mounted from a Secret
Secrets .env Secret Manager (CSI / External Secrets)
Network compose bridge NetworkPolicy: agent→Toolbox→DB only
Telemetry --telemetry-otlp → collector --telemetry-gcp → Cloud Trace/Monitoring
Identity local Keycloak Google Sign-In (authService: kind: google)
Scaling single container HPA 2–10, built-in connection pooling

The tools, authenticated parameters, and roles are identical across both —
only the sources: block changes (deploy/k8s/tools.yaml is generated from
toolbox/tools.yaml).

Catalog data flow

scripts/build_catalog.py streams grocery_store.inventory.json (70 MB of
products with Gemini embeddings), assigns SKUs, and loads an aligned catalog
into Postgres (price/stock) and Mongo (embeddings + sku), then builds the
vector_index. This guarantees a product returned by vector search exists, with
an authoritative price, in Postgres.

Mcp Ai Agents Mcp Toolbox Security Agent Docs ARCHITECTURE DIAGRAM (`mcp_ai_agents/mcp_toolbox_security_agent/docs/ARCHITECTURE_DIAGRAM.md`)

Technical Architecture — MCP Toolbox E-Commerce Security Demo

The diagram below shows every layer of the system and how MCP Toolbox acts as
the security control plane between the untrusted LLM layer and the databases.
Annotated numbers correspond to the ten security mechanisms documented in
SECURITY.md.

text
/* Detailed source-code truncated for AI context efficiency. */

Security mechanism quick-reference

# Mechanism Where enforced What it prevents
1 Custom named tools only — no execute_sql tools.yaml (10 tools) Arbitrary query power; attack surface = tool list
2 Authenticated parameters — username from JWT claim tools.yaml authServices Model requesting another user's data
3 Authorized invocations — authRequired:[keycloak_admin] tools.yaml admin tools Non-admins calling view_all_orders / update_inventory
4 SDK bound parameters — store_region fixed by app agent/agent.py bound_params Model choosing tenant / region
5 Parameterized queries — $1 … $n everywhere tools.yaml all SQL stmts SQL injection
6 Least-privilege DB roles — toolbox_app / toolbox_admin db/postgres/01_roles.sql Blast radius of a compromised tool
7 IAM / Workload Identity — cloud-sql-postgres, no password deploy/k8s/tools.yaml DB password in the cluster
8 Secrets via env-var interpolation — ${VAR} in tools.yaml tools.yaml + .env / Secret Manager Credentials in source code
9 Full observability — OTLP on every tool call --telemetry-otlp / --telemetry-gcp Silent misuse; every call is an audited trace
10 Network hardening — --allowed-hosts; K8s NetworkPolicy deploy/k8s/networkpolicy.yaml Agent reaching DBs directly; SSRF

Key insight: Everything to the left of the Toolbox boundary (the LLM,
its prompt, its tool arguments) is treated as untrusted input.
All enforcement happens inside Toolbox and in the database — below the agent,
making misuse structurally impossible rather than just discouraged.

Mcp Ai Agents Mcp Toolbox Security Agent Docs RUNBOOK (`mcp_ai_agents/mcp_toolbox_security_agent/docs/RUNBOOK.md`)

Live demo runbook

A ~6–8 minute talk demo. Every step has a UI action and a CLI fallback you
can run if a slide or click fails.

Before you go on stage

bash
scripts/bootstrap_local.sh          # ~3–5 min: build, start, seed catalog
scripts/verify_security.sh          # confirm all 11 checks pass

Open tabs: http://localhost:8080 (UI) and http://localhost:16687 (Jaeger).
For the live chat, set NEBIUS_API_KEY (Kimi-K2.6 agent) and GOOGLE_API_KEY
(Gemini embeddings for semantic search) in deploy/compose/.env, then
docker compose ... up -d agent-web. Otherwise use the deterministic buttons,
which need no API key.

Reset demo state any time:

bash
docker compose -f deploy/compose/docker-compose.yaml --env-file deploy/compose/.env \
  run --rm catalog          # re-seeds alice's cart + bob's order

The script

1 — Frame it (30s). "An agent that can touch a production database is a
security problem. The usual answer is an MCP server with execute_sql — the
agent can run anything. We did the opposite: MCP Toolbox gives the agent narrow
tools and becomes the trust boundary." Show docs/ARCHITECTURE.md diagram.

2 — Shop as alice (1m). Sign in as alice. In chat: "find me some dark
chocolate" → "add two of the first one" → "check out". (No API key? Use the
cart/refresh buttons after running the CLI below.) Point out: the agent passed a
sku, never a price or a username.

3 — Per-user scoping (1m). Click Refresh cart / Refresh orders — alice
sees only her data. Sign in as bob: different cart, different orders. Nothing
in the agent or the request said "alice" or "bob" — Toolbox derived it from the
login token.

4 — The block (1.5m, the centerpiece). Back as alice, in Cross-user
access test enter bob's order id (1) → Read order details. Result: a red
Blocked banner, zero rows. "She asked for order 1. Toolbox ran the query as
her. username is bound from her token — she can't pass it, can't forge it."

CLI fallback / proof:

bash
# inside the stack so the token issuer matches:
docker compose -f deploy/compose/docker-compose.yaml --env-file deploy/compose/.env \
  exec -T agent-web python3 - <<'PY'
import urllib.request,urllib.parse,json
def tok(u): 
    d=urllib.parse.urlencode({"client_id":"grocery-agent","grant_type":"password","username":u,"password":u+"123"}).encode()
    return json.load(urllib.request.urlopen("http://keycloak:8080/realms/grocery/protocol/openid-connect/token",d))["access_token"]
def call(t,p,h): 
    r=urllib.request.Request(f"http://toolbox:5000/api/tool/{t}/invoke",json.dumps(p).encode(),{"Content-Type":"application/json",h[0]:h[1]})
    return urllib.request.urlopen(r).read().decode()
print("alice -> bob's order:", call("get_order_details",{"order_id":1},("keycloak_token",tok("alice"))))
print("bob   -> bob's order:", call("get_order_details",{"order_id":1},("keycloak_token",tok("bob"))))
PY

5 — Why it's impossible, not just unlikely (1m). Click Show tool schemas.
Contrast: the Toolbox manifest lists username annotated authServices:[keycloak],
but the model's function signature is view_cart() / add_to_cart(quantity, sku)
— no username. "The model can't pass what isn't in its schema."

6 — Admin gating (1m). As alice, click view_all_orders → denied. Sign
in as carol (admin) → it returns every order. "Same tool, different token.
Only carol's token carries the grocery-admin audience — and that's role-driven
in Keycloak, she can't self-grant it."

7 — It's all audited (45s). Open Jaeger (http://localhost:16687), service
toolbox. Show the spans for the calls you just made — including the blocked one
(a successful, audited tool call that returned zero rows, not a silent drop).

8 — Land the plane (30s). Recap with docs/SECURITY.md: authenticated
parameters, authorized invocations, parameterized queries, least-privilege roles,
IAM/Workload Identity, observability. "Toolbox is the control plane. The agent is
outside the trust boundary — by construction." Show deploy/k8s/ for the GKE
shape (Workload Identity = no DB password at all).

One-command proof (if you only have 60 seconds)

bash
scripts/verify_security.sh

11 green checks: authenticated params, the cross-user block, no-token rejection,
admin allow/deny, SQL-injection-as-literal, and three least-privilege denials.

Troubleshooting

  • Toolbox restarting — it inits sources + OIDC eagerly; it converges once
    Keycloak's realm is imported (restart: on-failure). Give it ~60s after first
    boot. docker compose ... logs toolbox.
  • Chat returns 503 — NEBIUS_API_KEY isn't set (or GOOGLE_API_KEY if
    AGENT_PROVIDER=gemini); the security demo still works without it.
  • Chat works but search fails — semantic search needs GOOGLE_API_KEY
    (Gemini query embeddings); cart/checkout/orders still work without it.
  • Token rejected by Toolbox — only mint tokens inside the network
    (keycloak:8080); a host-minted token (localhost:8085) has a different
    issuer. scripts/get_token.sh is for inspecting claims, not calling Toolbox.
  • Port already in use — published host ports are 8080/5055/8085/16687/8899/
    5544/27117; change them in deploy/compose/docker-compose.yaml if needed.

Mcp Ai Agents Mcp Toolbox Security Agent Docs SECURITY (`mcp_ai_agents/mcp_toolbox_security_agent/docs/SECURITY.md`)

Security model — how MCP Toolbox constrains the agent

The agent is treated as untrusted. Ten mechanisms, layered, ensure that no
prompt, jailbreak, or malformed tool argument lets it exceed its authority. Each
is implemented in this repo and verified by scripts/verify_security.sh.

Mechanism map

# Mechanism Where What it stops
1 Custom tools, not execute_sql toolbox/tools.yaml — only 10 named tools; the Mongo vector index/path are hardcoded The agent never has arbitrary query power; the attack surface is the tool list
2 Authenticated parameters tools.yaml — username carries authServices:[{name: keycloak, field: preferred_username}] The model can't request another user's data; username isn't even in its tool schema
3 Authorized invocations tools.yaml — admin tools have authRequired:[keycloak_admin] Non-admins can't call view_all_orders / update_inventory
4 Bound parameters (SDK) agent/agent.py — bound_params={"store_region": ...} The model can't choose the tenant/region; it's fixed by the app
5 Parameterized queries tools.yaml — every statement uses $1..$n (no string interpolation) SQL injection; tool args are values, never SQL
6 Least-privilege DB roles db/postgres/01_roles.sql — toolbox_app / toolbox_admin, one per source A compromised tool can't DROP/UPDATE-catalog/DELETE-orders
7 IAM / Workload Identity deploy/k8s/ — cloud-sql-postgres with no password; KSA→GSA No DB password exists in the cluster at all
8 Secrets handling ${ENV} in tools.yaml; .env (local) / Secret Manager (GKE) Credentials never reach the model and aren't hardcoded
9 Observability --telemetry-otlp / --telemetry-gcp; observability/ Every tool call is an audited, traced event
10 Network hardening --allowed-hosts / --allowed-origins; deploy/k8s/networkpolicy.yaml Only agent→Toolbox→DB; the agent can't reach the DB directly

The headline: authenticated parameters (#2)

The view_cart tool is defined with a single parameter that the model never sees:

yaml
parameters:
  - name: username
    type: string
    authServices:
      - name: keycloak
        field: preferred_username   # taken from the verified token, not the model

Verified behavior (from the running stack):

  • The model-facing signature is view_cart() -> str — no username.
    (add_to_cart(quantity, sku), get_order_details(order_id) — same story.)
  • Calling view_cart with a body of {"username":"bob"} while presenting
    alice's token still returns alice's cart. The forged value is ignored; the
    claim wins.
  • Calling it with no token → HTTP 401 ("error parsing authenticated
    parameter"). Identity isn't optional.
  • get_order_details(order_id=) as alice → zero rows. Ownership is in
    the WHERE clause against the authenticated username; it can't be bypassed.

This is the difference between asking the model nicely and making it
impossible: identity is resolved deterministically by the server, below the
agent.

Admin gating is role-driven, not request-driven (#3)

view_all_orders and update_inventory use authRequired: [keycloak_admin],
whose audience is grocery-admin. In Keycloak, only carol holds the
grocery-admin client role, so the built-in audience-resolve mapper adds that
audience to her token automatically. alice/bob can't obtain it — even requesting
the scope explicitly is rejected ("Invalid scopes"). Verified: alice → 401,
carol → 200.

Honest caveat (the confused-deputy lesson): bound parameters (#4) and the
app's choice of which token/header to send are trusted to the application
layer. Toolbox stops the model; your app process must still be trustworthy.
Call this out — it's the same lesson the MCP Toolbox docs flag for bound params.

Defense in depth below the tools (#6)

Even if a tool were subverted, the database role caps the blast radius. toolbox_app
holds SELECT on products and SELECT/INSERT on orders — and nothing more:

text
UPDATE products ...  → permission denied
DELETE FROM orders   → permission denied
DROP TABLE orders    → must be owner of table

Verifying it yourself

bash
scripts/verify_security.sh

Runs 11 checks inside the stack (tokens minted via keycloak:8080 so the issuer
matches what Toolbox validates) covering #2, #3, #5, and #6. Traces for every
call appear in Jaeger (#9).

Production hardening (#7, #8, #10)

On GKE (deploy/k8s/): Cloud SQL via Workload Identity means no DB password in
the cluster; tools.yaml and secrets come from Secret Manager; a NetworkPolicy
ensures only app=agent-web can reach Toolbox and only Toolbox can reach the
databases. Swap the authService to kind: google for Google Sign-In — no other
change.

Mcp Ai Agents Mcp Toolbox Security Agent Docs Architecture Diagram (`mcp_ai_agents/mcp_toolbox_security_agent/docs/architecture-diagram.md`)

Technical architecture — MCP Toolbox as the security control plane

text
/* Detailed source-code truncated for AI context efficiency. */

Legend

  • Green (bold) — MCP Toolbox, the only component that touches data. The agent never holds a DB credential or runs raw SQL.
  • Red dashed — the untrusted zone: the LLM and its tool arguments. Anything here is treated as hostile.
  • Solid thick arrows — data-plane calls that Toolbox makes as a least-privilege role.
  • Dotted arrows — identity/token flow (JWT issuance + OIDC validation).
  • #1–#10 — the ten security mechanisms (full map in SECURITY.md).

Renders on GitHub, in mermaid.live, and VS Code's Mermaid preview.

--- METRICS ---

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#agents Browse agents catalog → #ai Browse ai catalog → #hacktoberfest Browse hacktoberfest catalog → #llm Browse llm catalog → #mcp Browse mcp catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →