@opengroundplan/core 0.1.1

package/catalog/sources/ai-llm.yaml

@@ -0,0 +1,508 @@
+# Groundplan source catalog — category: ai-llm
+#
+# Research date: 2026-07-18
+#
+# VERIFICATION METHOD
+#   license  : SPDX id determined by reading the repository's actual LICENSE file, fetched
+#              verbatim from raw.githubusercontent.com (primary source). Carve-out / ambiguous
+#              licenses (langfuse, litellm, MCP SDKs, open-webui, phoenix) had their full text
+#              read, not just the first line.
+#   stars    : scraped from the repo's github.com page (`aria-label="N users starred"`).
+#   lastCommit / archived : from github.com/<repo>/commits.atom (<updated>) and the archived
+#              banner on the repo page.
+#
+# ADVERSARIAL RE-VERIFICATION PASS (2026-07-18, independent second agent)
+#   All 16 entries re-checked from primary sources. Every root LICENSE re-fetched and matched
+#   against the recorded `spdx` — no mismatches. Additionally checked for defects the first pass
+#   could have missed: langgraph's monorepo subpackages (libs/checkpoint, checkpoint-postgres,
+#   checkpoint-sqlite, cli, sdk-py, langgraph) were each fetched individually and are all MIT,
+#   so the recommended checkpointer code is genuinely vendorable; promptfoo's LICENSE is a plain
+#   19-line MIT with no enterprise carve-out; qdrant and chroma carry no supplementary
+#   LICENSE_ADDITIONAL/NOTICE that would narrow the Apache-2.0 grant. All 16 URLs return 200 and
+#   none is archived. Both rename claims confirmed by following the redirect: vercel/ai-chatbot
+#   -> vercel/chatbot and jlowin/fastmcp -> PrefectHQ/fastmcp.
+#   NOTE: api.github.com remained rate-limited to 0 on the shared host IP across this pass too,
+#   so `license.spdx_id` and `stargazers_count` were still not byte-compared against the REST
+#   API. This is a weaker gap than it sounds — reading the full LICENSE text is strictly stronger
+#   than trusting `spdx_id`, which is a licensee-heuristic guess and cannot express the langfuse
+#   `ee/` or litellm `enterprise/` carve-outs at all. Star counts re-scraped independently and
+#   reproduced to within 0.01%. The genuinely unverified API-only fields are `disabled` and
+#   `pushed_at` across non-default branches.
+#
+# LICENSE GATE
+#   vendorable      = MIT, Apache-2.0, BSD-2/3, ISC, Unlicense, CC0, 0BSD (attribution kept for
+#                     Apache-2.0 and BSD).
+#   reference-only  = MPL-2.0, LGPL, EPL — read for ideas, copy no files.
+#   excluded        = GPL/AGPL/SSPL/BUSL/source-available/unlicensed.
+#   Two entries carry carve-outs that are NOT vendorable and are called out in whatToAvoid:
+#   langfuse (`ee/`, `web/src/ee/`) and — dropped, see droppedCandidates — litellm (`enterprise/`).
+#   pgvector ships the PostgreSQL License, which is BSD-2-equivalent but not on the enumerated
+#   allowlist; flagged for one-time sign-off.
+#
+# No repo below is archived. Every one is actively maintained: the oldest last-commit date in
+# the list is 2026-06-28 (cloudflare/agents-starter), i.e. every entry has a commit within the
+# last three weeks. Nothing here is anywhere near the 18-month staleness threshold.
+
+category: ai-llm
+
+sources:
+  # ---------------------------------------------------------------- chat / app shells
+  - name: vercel/chatbot
+    url: https://github.com/vercel/chatbot
+    stars: 20639
+    spdx: Apache-2.0
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-08"
+    complexity: standard
+    stack: TypeScript, Next.js 15 (App Router), AI SDK 5, Drizzle, Postgres, NextAuth
+    whatToBorrow: >-
+      The reference full-stack AI chat app. Adapt `app/(chat)/api/chat/route.ts` (streaming
+      POST handler, resumable stream ids, stop/regenerate), `lib/db/schema.ts` (chat, message,
+      vote, document tables — a proven message-persistence model including parts/attachments),
+      `lib/ai/providers.ts` (provider indirection so the model id is config, not a literal),
+      `app/(auth)/auth.ts` for NextAuth + guest-session flow, and `middleware.ts`. The
+      artifacts/canvas system under `artifacts/` is the best open reference for
+      side-panel generative UI.
+    whatToAvoid: >-
+      Assumes the Vercel platform end to end — Vercel Blob for uploads, Vercel Postgres, Redis
+      for resumable streams, and AI Gateway for model routing; each needs an adapter seam before
+      it is portable. The artifacts feature is a large, tangled subsystem and is the main thing
+      to strip for a minimal chat template. NOTE: repo was renamed from `vercel/ai-chatbot` —
+      the old URL redirects, but pin the new name. Apache-2.0 requires shipping the NOTICE.
+    proposedLayerIds:
+      - ai-chat-nextjs-ai-sdk
+      - db-postgres-drizzle
+      - auth-nextauth
+      - ai-provider-gateway
+      - storage-vercel-blob
+
+  - name: assistant-ui/assistant-ui
+    url: https://github.com/assistant-ui/assistant-ui
+    stars: 11147
+    spdx: MIT
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-18"
+    complexity: standard
+    stack: TypeScript, React, Radix-style headless primitives, shadcn/ui, AI SDK + LangGraph adapters
+    whatToBorrow: >-
+      Headless chat primitives (`Thread`, `Composer`, `MessagePrimitive`, `BranchPicker`) that
+      cleanly separate chat state from styling — the right shape for a template that must
+      restyle per project. Borrow the runtime-adapter interface (`useChatRuntime`, LangGraph and
+      AI SDK runtimes) as the seam between UI and backend, the generative-UI registry that maps a
+      tool name to a React component, and the `npx assistant-ui init` shadcn-registry approach
+      to component scaffolding — directly relevant prior art for Groundplan itself.
+    whatToAvoid: >-
+      Primitive API still shifts between minor versions; pin exactly. React-only, so it cannot
+      back a Vue/Svelte template. Parts of the docs steer toward the hosted assistant-cloud
+      product for thread persistence — keep persistence in your own database layer.
+    proposedLayerIds:
+      - ui-chat-assistant-ui
+      - ui-shadcn
+      - ai-generative-ui
+      - ai-chat-nextjs-ai-sdk
+
+  # ---------------------------------------------------------------- SDK / agent frameworks
+  - name: vercel/ai
+    url: https://github.com/vercel/ai
+    stars: 25631
+    spdx: Apache-2.0
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-17"
+    complexity: professional
+    stack: TypeScript monorepo, provider packages, React/Svelte/Vue bindings
+    whatToBorrow: >-
+      Depend on the package; borrow the patterns from `examples/`. Specifically
+      `examples/next-openai` route handlers for `streamText`, `generateObject` (zod-validated
+      structured output), tool definitions with `inputSchema`, and multi-step `stopWhen` agent
+      loops. The `@ai-sdk/provider` interface is the cleanest model-agnostic abstraction to copy
+      the shape of, so a template can swap OpenAI/Anthropic/Google by changing one config value.
+    whatToAvoid: >-
+      Do not vendor the library source — take it as a dependency. The v4→v5 migration renamed
+      core surface (`maxTokens`→`maxOutputTokens`, message `parts`, `inputSchema`), so any
+      tutorial or snippet older than the pinned version will not compile. Provider packages
+      version independently of the core.
+    proposedLayerIds:
+      - ai-sdk-core
+      - ai-tools-zod
+      - ai-structured-output
+      - ai-provider-openai
+      - ai-provider-anthropic
+
+  - name: openai/openai-agents-python
+    url: https://github.com/openai/openai-agents-python
+    stars: 27994
+    spdx: MIT
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-17"
+    complexity: simple
+    stack: Python 3.9+, pydantic, optional LiteLLM shim
+    whatToBorrow: >-
+      The smallest credible agent framework — few primitives (Agent, Runner, handoffs,
+      guardrails, sessions), readable in an afternoon, ideal for the simple rung. Borrow the
+      `Session` protocol with its SQLite/SQLAlchemy implementations as a drop-in conversation-memory
+      layer, the input/output guardrail pattern (a cheap model gates an expensive one), the
+      tracing processor interface, and `examples/basic` + `examples/mcp` as template seeds.
+    whatToAvoid: >-
+      OpenAI-first: non-OpenAI providers route through the optional LiteLLM extra and lose some
+      features (hosted tools, some tracing). Built-in tracing posts to OpenAI's backend unless
+      explicitly disabled — set that off by default in any generated template. The voice and
+      realtime extras drag in heavy audio deps; keep them out of the base layer.
+    proposedLayerIds:
+      - ai-agent-python-openai-agents
+      - ai-guardrails
+      - ai-session-memory
+      - mcp-client-python
+
+  - name: pydantic/pydantic-ai
+    url: https://github.com/pydantic/pydantic-ai
+    stars: 18636
+    spdx: MIT
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-18"
+    complexity: standard
+    stack: Python 3.9+, pydantic v2, FastAPI-friendly, OpenTelemetry
+    whatToBorrow: >-
+      The typed-agent pattern: `Agent[DepsType, OutputType]` with dependency injection via
+      `RunContext`, so tools receive a typed deps object (db pool, http client) instead of
+      reaching for globals — the cleanest testability story in the Python agent space. Borrow
+      `output_type=SomeModel` for validated structured output with automatic retry on validation
+      failure, the `pydantic_evals` package for dataset-driven evals, and `examples/rag.py`
+      (pgvector-backed retrieval) and `examples/bank_support.py` as template seeds.
+    whatToAvoid: >-
+      Still evolving quickly; minor releases have moved public surface, so pin exactly and
+      expect churn. Documentation steers toward Logfire (Pydantic's paid product) for
+      observability — the underlying instrumentation is plain OpenTelemetry, so wire it to any
+      OTel collector instead of hardcoding a Logfire token.
+    proposedLayerIds:
+      - ai-agent-python-pydantic-ai
+      - ai-structured-output
+      - evals-pydantic-evals
+      - obs-otel-llm
+
+  - name: langchain-ai/langgraph
+    url: https://github.com/langchain-ai/langgraph
+    stars: 37569
+    spdx: MIT
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-15"
+    complexity: professional
+    stack: Python + JS, graph runtime, Postgres/SQLite checkpointers
+    whatToBorrow: >-
+      The durable-execution model for agents that must survive restarts. Borrow the `StateGraph`
+      + reducer-annotated state (`Annotated[list, add_messages]`), the checkpointer interface
+      with its `langgraph-checkpoint-postgres` and sqlite implementations (this is the piece
+      worth adapting — thread-scoped, resumable conversation state), `interrupt()` for
+      human-in-the-loop approval gates, the store abstraction for long-term memory, and
+      `langgraph.json` as a deployment manifest.
+    whatToAvoid: >-
+      Pulls the LangChain ecosystem's gravity with it; keep the graph layer isolated so a
+      template is not forced into `langchain-core` abstractions everywhere. Graph indirection is
+      genuine over-engineering for a single-turn or linear agent — do not make this the default
+      rung. LangGraph Platform (the managed deploy/Studio product) is commercial and is not what
+      this MIT repo grants; self-host the runtime instead.
+    proposedLayerIds:
+      - ai-agent-graph-langgraph
+      - ai-checkpoint-postgres
+      - ai-human-in-the-loop
+      - ai-long-term-memory
+
+  - name: cloudflare/agents-starter
+    url: https://github.com/cloudflare/agents-starter
+    stars: 1294
+    spdx: MIT
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-06-28"
+    complexity: simple
+    stack: TypeScript, Cloudflare Workers, Durable Objects, agents SDK, AI SDK, Vite, Tailwind
+    whatToBorrow: >-
+      A genuinely small, complete edge-agent template — the whole repo is close to template-shaped
+      already. Borrow `src/server.ts` (an `AIChatAgent` subclass whose per-conversation state
+      lives in a Durable Object, giving stateful chat with zero external database),
+      `wrangler.jsonc` for DO bindings and migrations, `src/tools.ts` for the
+      confirmation-required-vs-auto-execute tool split (human-in-the-loop without a graph
+      engine), and the built-in task scheduling API for agents that wake on a cron.
+    whatToAvoid: >-
+      Hard Cloudflare lock-in — Durable Objects, Workers AI bindings and `wrangler` have no
+      portable equivalent, so this cannot be a generic edge layer. Small repo that tracks the
+      fast-moving `agents` SDK, so upstream breaking changes land here without ceremony. State
+      lives in a DO with no export path unless you add one.
+    proposedLayerIds:
+      - ai-agent-cloudflare-workers
+      - edge-durable-objects
+      - ai-scheduled-tasks
+
+  # ---------------------------------------------------------------- MCP
+  - name: PrefectHQ/fastmcp
+    url: https://github.com/PrefectHQ/fastmcp
+    stars: 26253
+    spdx: Apache-2.0
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-18"
+    complexity: professional
+    stack: Python 3.10+, pydantic, httpx, uv
+    whatToBorrow: >-
+      The most complete Python MCP server framework. Borrow the decorator surface
+      (`@mcp.tool`, `@mcp.resource("uri://{param}")`, `@mcp.prompt`) with automatic schema
+      generation from type hints, the auth provider set (OAuth proxy, JWT, bearer — the piece
+      almost every other MCP example omits), `fastmcp.json` as a declarative server manifest,
+      server composition/mounting and the OpenAPI-to-MCP generator, and above all the in-memory
+      `Client(mcp_server)` transport, which makes MCP servers unit-testable without a subprocess.
+    whatToAvoid: >-
+      Deliberately diverged from the official SDK: FastMCP v1 was upstreamed into
+      `modelcontextprotocol/python-sdk`, v2 is a separate, much larger project — pick one per
+      template and do not mix imports. Parts of the docs route to FastMCP Cloud for deployment.
+      Surface area is far beyond a minimal server, so strip hard for the simple rung.
+      Apache-2.0: keep the NOTICE. Repo moved from `jlowin/fastmcp` to the PrefectHQ org.
+    proposedLayerIds:
+      - mcp-server-python-fastmcp
+      - mcp-auth-oauth
+      - mcp-transport-streamable-http
+      - mcp-testing
+
+  - name: modelcontextprotocol/typescript-sdk
+    url: https://github.com/modelcontextprotocol/typescript-sdk
+    stars: 12883
+    # Not a single-id license: the LICENSE file is a live MIT->Apache-2.0 transition document,
+    # so parts of the tree are still MIT. Both are vendorable, but do not restate one id.
+    spdx: Apache-2.0 AND MIT
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-17"
+    complexity: standard
+    stack: TypeScript, zod, Express-compatible HTTP transports
+    whatToBorrow: >-
+      The canonical TS MCP implementation, and the reference for the TypeScript rung. Borrow
+      `McpServer` with zod-schema tool registration, the `StreamableHTTPServerTransport` wiring
+      including session-id management and resumability, `StdioServerTransport` for local
+      editor-launched servers, and the worked servers in `src/examples/server/`
+      (`simpleStreamableHttp`, `sslStreamableHttp`, stateless variants) — these are close to
+      copy-paste template bodies. The OAuth provider skeleton covers the remote-server case.
+    whatToAvoid: >-
+      LICENSE documents a live MIT→Apache-2.0 transition: new code is Apache-2.0, but
+      contributions from authors who have not consented to relicensing remain MIT. Both are
+      vendorable, but ship the LICENSE verbatim rather than restating a single SPDX id.
+      Transport API has churned (HTTP+SSE is legacy, superseded by Streamable HTTP) — target
+      Streamable HTTP only and pin the SDK version.
+    proposedLayerIds:
+      - mcp-server-typescript
+      - mcp-transport-streamable-http
+      - mcp-auth-oauth
+      - mcp-client-typescript
+
+  # ---------------------------------------------------------------- evals & observability
+  - name: promptfoo/promptfoo
+    url: https://github.com/promptfoo/promptfoo
+    stars: 23389
+    spdx: MIT
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-18"
+    complexity: standard
+    stack: TypeScript/Node CLI, YAML config, GitHub Actions integration
+    whatToBorrow: >-
+      Declarative, config-first evals — the natural fit for a scaffolder because the deliverable
+      is a single file. Borrow the `promptfooconfig.yaml` schema (providers × prompts × tests,
+      with `assert` blocks), the assertion taxonomy (deterministic `contains`/`is-json`/
+      `javascript` alongside model-graded `llm-rubric` and `factuality`), the matrix-expansion
+      idea of running every prompt against every provider to compare, the caching layer that
+      makes reruns cheap, and the CI recipe that fails a PR when eval scores regress.
+    whatToAvoid: >-
+      Config sprawls quickly once you use variables, scenarios and derived metrics; template a
+      deliberately small subset. Node-only, so a Python project gains a second toolchain — pair
+      or swap with deepeval there. The red-team/scanning features and the hosted sharing view
+      shade into the commercial offering; keep generated templates on local `promptfoo eval`.
+    proposedLayerIds:
+      - evals-promptfoo
+      - ci-evals-github-actions
+      - redteam-promptfoo
+
+  - name: confident-ai/deepeval
+    url: https://github.com/confident-ai/deepeval
+    stars: 16937
+    spdx: Apache-2.0
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-16"
+    complexity: standard
+    stack: Python, pytest integration, LLM-as-judge metrics
+    whatToBorrow: >-
+      Evals as unit tests — the Python counterpart to promptfoo. Borrow the pytest integration
+      (`assert_test(test_case, [metric])` in a normal `test_*.py`, run via `deepeval test run`),
+      which means eval failures surface in the same CI job as the rest of the suite. The RAG
+      metric set is the real asset: faithfulness, answer relevancy, contextual precision/recall
+      map one-to-one onto retriever-vs-generator debugging. `GEval` (criteria in plain English)
+      and the synthesizer for generating goldens from documents are both worth templating.
+    whatToAvoid: >-
+      Every model-graded metric is an LLM call, so a naive suite is slow and costs real money on
+      each CI run — template a small smoke set and gate the full suite behind a label. Docs push
+      the Confident AI hosted platform for reporting; the local path works standalone but is
+      less documented. Judge quality is bounded by the judge model, so pin it via config.
+    proposedLayerIds:
+      - evals-deepeval
+      - evals-pytest
+      - evals-rag-metrics
+
+  - name: langfuse/langfuse
+    url: https://github.com/langfuse/langfuse
+    stars: 31381
+    spdx: MIT
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-17"
+    complexity: enterprise
+    stack: TypeScript, Next.js, tRPC, Postgres + ClickHouse + Redis + S3/MinIO, OpenTelemetry
+    whatToBorrow: >-
+      The self-hostable LLM observability stack. Borrow the OTel-based tracing integration
+      (traces/spans/generations with token and cost attribution), the prompt-management API —
+      versioned, labelled prompts fetched at runtime with a local fallback, which is exactly the
+      "no static values in code" pattern applied to prompts — the dataset + eval-run schema for
+      regression tracking, and the self-host `docker-compose.yml` as a reference topology.
+    whatToAvoid: >-
+      LICENSE CARVE-OUT — the MIT grant explicitly excludes everything under `ee/`,
+      `web/src/ee/` and related enterprise paths. Copy no file from those directories; read the
+      LICENSE preamble before vendoring anything. Operationally heavy: a real deployment is five
+      services (Postgres, ClickHouse, Redis, S3/MinIO, web+worker), far too much for a starter
+      template — scaffold the SDK integration and point at either Langfuse Cloud or a separately
+      provisioned instance.
+    proposedLayerIds:
+      - obs-langfuse
+      - obs-otel-llm
+      - prompt-management-langfuse
+      - db-clickhouse
+
+  # ---------------------------------------------------------------- vector stores
+  - name: pgvector/pgvector
+    url: https://github.com/pgvector/pgvector
+    stars: 22242
+    spdx: PostgreSQL
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-11"
+    complexity: standard
+    stack: C Postgres extension; clients for Python, Node, Go, Rust, Ruby, Java
+    whatToBorrow: >-
+      The default answer for teams that already run Postgres and do not want a second datastore.
+      Borrow the migration shape — `CREATE EXTENSION vector`, a `vector(1536)` column, then an
+      HNSW index (`USING hnsw (embedding vector_cosine_ops)`) — plus the README's index tuning
+      guidance (`m`/`ef_construction` at build time, `hnsw.ef_search` at query time) and the
+      distance operator table (`<->` L2, `<=>` cosine, `<#>` inner product). The halfvec and
+      binary quantization sections matter once dimensions get large. Composes directly with
+      Drizzle or SQLAlchemy in the same transaction as relational data.
+    whatToAvoid: >-
+      LICENSE FLAG — the PostgreSQL License is BSD-2-equivalent and permissive, but it is not on
+      the enumerated vendorable allowlist; get a one-time sign-off before copying source (in
+      practice a template only depends on the extension and writes its own DDL, so exposure is
+      near zero — keep the copyright notice regardless). Operationally: HNSW index builds are
+      memory-hungry (`maintenance_work_mem`) and slow on large tables, and recall silently
+      degrades if `ef_search` is left at the default. Requires the extension to be available,
+      which not every managed Postgres offers.
+    proposedLayerIds:
+      - db-postgres-pgvector
+      - db-migrations-vector
+
+  - name: chroma-core/chroma
+    url: https://github.com/chroma-core/chroma
+    stars: 28821
+    spdx: Apache-2.0
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-18"
+    complexity: simple
+    stack: Rust core with Python and TypeScript clients; embedded or server mode
+    whatToBorrow: >-
+      The lowest-friction vector store, and the right choice for the simple rung:
+      `PersistentClient(path=...)` gives a working RAG demo with no container and no service to
+      run. Borrow the collection API (`add`/`query` with documents, metadatas, ids and metadata
+      `where` filters), the pluggable embedding-function adapters that keep the embedding model
+      a config value, and the `chroma run` + Docker path as the upgrade step once the embedded
+      store is outgrown.
+    whatToAvoid: >-
+      A history of breaking client changes across 0.4 → 0.5 → 1.x (client construction and
+      settings were reworked more than once) — pin exactly and expect migration work. Embedded
+      mode is single-process and does not scale past a demo, so design the retriever behind an
+      interface from day one. Docs steer toward Chroma Cloud for the hosted path.
+    proposedLayerIds:
+      - vector-chroma
+      - vector-embedded-local
+      - rag-retriever-interface
+
+  - name: qdrant/qdrant
+    url: https://github.com/qdrant/qdrant
+    stars: 33379
+    spdx: Apache-2.0
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-17"
+    complexity: professional
+    stack: Rust server; gRPC + REST; official Python/JS/Go/Rust clients
+    whatToBorrow: >-
+      The production rung for a dedicated vector service. Borrow the deployment surface, not the
+      source: a `docker-compose.yml` pinned to a version with a named volume, a `config.yaml`
+      override for storage and optimizer settings, and the collection-creation call that sets
+      distance metric, HNSW parameters and scalar/binary quantization (the memory lever that
+      makes large collections affordable). Payload indexes plus filtered search give real hybrid
+      metadata+vector queries, and named vectors support multi-embedding collections.
+    whatToAvoid: >-
+      This is a Rust database server, not a template — vendoring source is the wrong move;
+      vendor the compose file, config and client wiring. It is a second stateful service to run,
+      back up and upgrade, which is unjustified below roughly a million vectors (use pgvector or
+      Chroma there). Some managed conveniences are Qdrant Cloud only. Snapshot/restore needs
+      explicit setup or a restart loses data.
+    proposedLayerIds:
+      - vector-qdrant
+      - vector-hybrid-search
+      - docker-compose-vector
+      - rag-retriever-interface
+
+  # ---------------------------------------------------------------- enterprise RAG reference
+  - name: Azure-Samples/azure-search-openai-demo
+    url: https://github.com/Azure-Samples/azure-search-openai-demo
+    stars: 7708
+    spdx: MIT
+    licenseClass: vendorable
+    maintained: true
+    lastCommit: "2026-07-17"
+    complexity: enterprise
+    stack: Python (Quart) backend, React/TypeScript frontend, Bicep + azd IaC, Azure AI Search
+    whatToBorrow: >-
+      The most complete open reference for regulated-context RAG. Borrow
+      `app/backend/approaches/` — `retrievethenread.py` and `chatreadretrieveread.py` are the
+      two canonical RAG topologies written out cleanly, including query rewriting before
+      retrieval. Also worth adapting: the ingestion pipeline (`prepdocs.py`) with page-aware
+      chunking and overlap; document-level access control that trims results by user group
+      (the feature nearly every RAG demo omits and every enterprise requires); citation
+      plumbing that carries source page references through to a clickable UI; managed-identity
+      auth with no keys in config; and `infra/` + `azure.yaml` as an azd-provisioned IaC model.
+    whatToAvoid: >-
+      Deep Azure lock-in — Azure AI Search, Azure OpenAI, Document Intelligence and Entra ID are
+      assumed throughout; the approach classes are portable, the infrastructure is not. Running
+      it is genuinely expensive (AI Search plus Document Intelligence bill per document). Large
+      surface area to strip, and the repo doubles as a feature showcase, so many code paths are
+      guarded by feature flags you will need to prune.
+    proposedLayerIds:
+      - rag-azure-ai-search
+      - iac-bicep-azd
+      - auth-entra-id
+      - rag-doc-ingestion
+      - rag-citations
+      - rag-acl-filtering
+
+droppedCandidates:
+  - "open-webui/open-webui (145868 stars, active) — LICENSE is a custom 'Open WebUI License': BSD-3 plus a branding-restriction clause forbidding removal of Open WebUI branding. Not an OSI permissive license; excluded from vendoring."
+  - "Arize-ai/phoenix (10615 stars, active) — LICENSE is Elastic License 2.0 (ELv2), source-available with a no-managed-service restriction. Excluded."
+  - "BerriAI/litellm (53950 stars, MIT, active 2026-07-18) — strong LLM gateway (proxy config.yaml with model_list, fallbacks, budgets, virtual keys), but the LICENSE carves the entire enterprise/ directory out of the MIT grant. Dropped only to hold the list at 16; re-add as an ai-gateway-litellm layer, copying nothing from enterprise/."
+  - "run-llama/create-llama (1489 stars, MIT) — conceptually the closest prior art to Groundplan (a RAG app scaffolder), but last commit 2025-07-16, roughly 12 months stale; the effort moved into the LlamaIndexTS monorepo. Not stale by the 18-month rule, but too unmaintained to be a primary source."
+  - "langchain-ai/langchain (142041 stars, MIT) and run-llama/llama_index (50930 stars, MIT) — both healthy and permissive, but they are sprawling frameworks rather than adaptable starters; LangGraph and PydanticAI give a better template surface for the same use cases."
+  - "infiniflow/ragflow (85337 stars, Apache-2.0, active) — excellent DeepDoc layout-aware parsing and chunking templates, but the deployable unit is a monolith over Elasticsearch/Infinity + MySQL + MinIO + Redis; too heavy to reduce to a template. Worth revisiting for a rag-doc-parsing layer only."
+  - "lancedb/lancedb (10929 stars, Apache-2.0, active) — embedded vector store on object storage with time-travel; dropped as redundant with Chroma at the simple rung, but the better pick if S3-backed serverless retrieval is wanted."
+  - "modelcontextprotocol/python-sdk (23649 stars, MIT, active) — the official Python MCP SDK; dropped only because FastMCP covers the same rung with more batteries. Prefer this one when a template must minimize dependencies."
+  - "weaviate/weaviate (16608 stars, BSD-3-Clause, active), deepset-ai/haystack (25936, Apache-2.0), agno-agi/agno (41231, Apache-2.0), mem0ai/mem0 (61123, Apache-2.0), CopilotKit/CopilotKit (36140, MIT), Chainlit/chainlit (12318, Apache-2.0), traceloop/openllmetry (7311, Apache-2.0), lastmile-ai/mcp-agent (8430, Apache-2.0) — all verified vendorable and maintained; held back to keep the list at 16. Any is a valid second-wave addition."
+  - "vercel-labs/ai-sdk-preview-rag (409 stars, MIT) and streamlit/llm-examples (924 stars, Apache-2.0) — good minimal RAG/chat references but low-activity preview repos (last commits 2025-12); use as snippet sources, not template bases."