feat: add the knowledge assistant example

Author: ksachdeva

.env.example

@@ -1,9 +1,14 @@
 SESSION_STORAGE_TYPE=memory
 # SESSION_STORAGE_TYPE=db
 
+# example for sqlite
 ADK_DATABASE_URL=sqlite:///./chatkit.db
 
+# example for postgres
+# ADK_DATABASE_URL=postgresql://POSTGRES_USERNAME:POSTGRES_PASSWORD@POSTGRES_HOST:POSTGRES_PORT/DB_NAME
+
 gpt41_agent={"llm":{"model_name": "azure/gpt-4.1", "provider_args" : {"api_key": "xx", "api_base": "", "api_version": "2025-03-01-preview"}}}
 gpt41_mini_agent={"llm":{"model_name": "azure/gpt-4.1-mini", "provider_args" : {"api_key": "xx", "api_base": "", "api_version": "2025-03-01-preview"}}}
 
 
+DATA_DIR=/workspaces/adk-chatkit/examples/data

examples/backend/pyproject.toml

@@ -10,9 +10,17 @@ dependencies = [
     "fastapi-cognito>=2.9.0",
     "pydantic>=2.11.7",
     "pydantic-settings>=2.10.1",
-    "google-adk>=1.16.0",    
+    "google-adk>=1.16.0",
     "litellm>=1.76.3",
     "adk-chatkit",
+    "langchain-community>=0.4",
+    "langchain-core>=1.0.0",
+    "lancedb>=0.25.2",
+    "langchain-openai>=1.0.1",
+    "langchain-ollama>=1.0.0",
+    "pypdf>=6.1.3",
+    "beautifulsoup4>=4.14.2",
+    "lxml>=6.0.2",
 ]
 
 [tool.ruff]

examples/backend/src/backend/_app.py

@@ -1,5 +1,4 @@
 import functools
-import logging
 from contextlib import asynccontextmanager
 from typing import AsyncContextManager, AsyncGenerator, Callable, Self
 
@@ -12,10 +11,9 @@
 from ._runner_manager import RunnerManager
 from .api.facts import router as facts_router
 from .api.health import router as health_router
+from .api.knowledge import router as knowledge_router
 from .api.support import router as support_router
 
-_LOGGER = logging.getLogger(__name__)
-
 
 @asynccontextmanager
 async def internal_lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
@@ -56,3 +54,4 @@ def __init__(
         self.include_router(health_router, tags=["healthcheck"])
         self.include_router(support_router, prefix="/support", tags=["support"])
         self.include_router(facts_router, prefix="/facts", tags=["facts"])
+        self.include_router(knowledge_router, prefix="/knowledge", tags=["knowledge"])

examples/backend/src/backend/_config.py

@@ -1,18 +1,37 @@
 import os
 from enum import Enum
+from pathlib import Path
 from typing import Annotated, Any, Literal
 
-from pydantic import AnyUrl, BeforeValidator, computed_field
+from pydantic import AnyUrl, BaseModel, BeforeValidator, SecretStr, computed_field
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 from .agents._config import AgentConfig
 
 
+class EmbeddingModelType(str, Enum):
+    openai = "openai"
+    azure_openai = "azure_openai"
+    ollama = "ollama"
+
+
 class SessionStorageType(str, Enum):
     memory = "memory"
     db = "db"
 
 
+class EmbedderSettings(BaseModel):
+    provider_type: EmbeddingModelType
+    model_name: str
+    api_key: SecretStr | None = None
+    api_endpoint: str | None = None
+    api_version: str | None = None
+    api_deployment: str | None = None
+
+    chunk_size: int = 1200
+    chunk_overlap: int = 100
+
+
 def parse_cors(v: Any) -> list[str] | str:
     if isinstance(v, str) and not v.startswith("["):
         return [i.strip() for i in v.split(",")]
@@ -56,7 +75,12 @@ def all_cors_origins(self) -> list[str]:
 
     AIRLINE_APP_NAME: str = "airline"
     FACTS_APP_NAME: str = "facts"
+    KNOWLEDGE_APP_NAME: str = "knowledge"
+
+    DATA_DIR: Path
 
     SESSION_STORAGE_TYPE: SessionStorageType = SessionStorageType.memory
 
     ADK_DATABASE_URL: str | None = None
+
+    embedder: EmbedderSettings | None = None

examples/backend/src/backend/_dishka_providers.py

@@ -4,11 +4,13 @@
 from google.adk.sessions.base_session_service import BaseSessionService
 from google.adk.sessions.database_session_service import DatabaseSessionService
 from google.adk.sessions.in_memory_session_service import InMemorySessionService
+from langchain_core.vectorstores import VectorStore
 
 from ._config import SessionStorageType, Settings
 from ._runner_manager import RunnerManager
 from .agents.airline import AirlineSupportChatkitServer
 from .agents.facts import FactsChatkitServer
+from .agents.knowledge import KnowledgeAssistantChatkitServer, make_vector_store
 
 
 class SessionServiceProvider(Provider):
@@ -24,6 +26,18 @@ async def get_service(self, settings: Settings) -> BaseSessionService:
         return InMemorySessionService()  # type: ignore
 
 
+class VectorStoreProvider(Provider):
+    scope = Scope.APP
+
+    settings = from_context(provides=Settings, scope=Scope.APP)
+
+    @provide
+    async def get_vector_store(self, settings: Settings) -> VectorStore:
+        if settings.embedder is None:
+            raise ValueError("Embedder settings must be provided to create a vector store.")
+        return make_vector_store(settings)
+
+
 def get_providers() -> list[BaseProvider]:
     runner_provider = Provider(scope=Scope.APP)
     runner_provider.from_context(Settings)
@@ -40,10 +54,16 @@ def get_providers() -> list[BaseProvider]:
     facts_server_provider.from_context(Settings)
     facts_server_provider.provide(FactsChatkitServer)
 
+    knowledge_server_provider = Provider(scope=Scope.APP)
+    knowledge_server_provider.from_context(Settings)
+    knowledge_server_provider.provide(KnowledgeAssistantChatkitServer)
+
     return [
         runner_provider,
         SessionServiceProvider(),
+        VectorStoreProvider(),
         adk_store_provider,
         airline_support_server_provider,
         facts_server_provider,
+        knowledge_server_provider,
     ]

examples/backend/src/backend/agents/knowledge/__init__.py

@@ -0,0 +1,15 @@
+from ._agent import KnowledgeAgent
+from ._documents import DOCUMENTS, DOCUMENTS_BY_FILENAME, DOCUMENTS_BY_ID, DOCUMENTS_BY_STEM, as_dicts
+from ._server import KnowledgeAssistantChatkitServer
+from ._vector_store import make_vector_store
+
+__all__ = [
+    "KnowledgeAgent",
+    "KnowledgeAssistantChatkitServer",
+    "DOCUMENTS",
+    "DOCUMENTS_BY_ID",
+    "DOCUMENTS_BY_FILENAME",
+    "DOCUMENTS_BY_STEM",
+    "as_dicts",
+    "make_vector_store",
+]

examples/backend/src/backend/agents/knowledge/_agent.py

@@ -0,0 +1,62 @@
+from typing import Any
+
+from adk_chatkit import remove_widgets_and_client_tool_calls
+from google.adk.agents.callback_context import CallbackContext
+from google.adk.agents.llm_agent import LlmAgent, ToolUnion
+from google.adk.models.lite_llm import LiteLlm
+from google.adk.models.llm_request import LlmRequest
+from google.adk.models.llm_response import LlmResponse
+from google.adk.tools.base_tool import BaseTool
+from google.adk.tools.tool_context import ToolContext
+from google.genai import types as genai_types
+
+_INSTRUCTIONS = """You are a **Federal Reserve Knowledge Assistant agent**.
+
+**Source library**
+You must use the following documents (refer to them by these exact filenames):
+- `01_fomc_statement_2025-09-17.html`
+- `02_implementation_note_2025-09-17.html`
+- `03_sep_tables_2025-09-17.pdf`
+- `04_sep_tables_2025-09-17.html`
+- `05_press_conference_transcript_2025-09-17.pdf`
+- `06_bls_cpi_2025-08.html`
+- `07_bea_gdp_q2_2025_second_estimate.pdf`
+- `08_fed_mpr_2025-06.pdf`
+
+These files contain the definitive information about the September 2025 FOMC meeting, projections, and related economic indicators.
+
+**Your task**
+- Always call the `file_search` tool before responding. Use the passages it returns as your evidence.
+- Compose a concise answer (2-4 sentences) grounded **only** in the retrieved passages.
+- Every factual sentence must include a citation in the format `(filename, page/section)` using the filenames listed above. If you cannot provide such a citation, say "I don't see that in the knowledge base." instead of guessing.
+- After the answer, optionally list key supporting bullets—each bullet needs its own citation.
+- Finish with a `Sources:` section listing each supporting document on its own line: `- filename (page/section)`. Use the exact filenames shown above so the client can highlight the source documents. Do not omit this section even if there is only one source.
+
+**Interaction guardrails**
+1. Ask for clarification when the question is ambiguous.
+2. Explain when the knowledge base does not contain the requested information.
+3. Never rely on external knowledge or unstated assumptions.
+
+Limit the entire response with citation to 2-3 sentences.
+
+""".strip()
+
+
+class KnowledgeAgent(LlmAgent):
+    def __init__(
+        self,
+        llm: LiteLlm,
+        tools: list[ToolUnion],
+        generate_content_config: genai_types.GenerateContentConfig | None = None,
+    ) -> None:
+        self._llm = llm
+
+        super().__init__(
+            name="knowledge_assistant",
+            description="Federal Reserve Knowledge Assistan",
+            model=self._llm,
+            instruction=_INSTRUCTIONS,
+            tools=tools,
+            before_model_callback=[remove_widgets_and_client_tool_calls],
+            generate_content_config=generate_content_config,
+        )

examples/backend/src/backend/agents/knowledge/_documents.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Iterable
+
+
+def _normalise(value: str) -> str:
+    return value.strip().lower()
+
+
+def _slugify(value: str) -> str:
+    return "".join(ch for ch in value.lower() if ch.isalnum())
+
+
+@dataclass(frozen=True, slots=True)
+class DocumentMetadata:
+    id: str
+    filename: str
+    title: str
+    description: str | None = None
+
+    @property
+    def stem(self) -> str:
+        return Path(self.filename).stem
+
+
+DOCUMENTS: tuple[DocumentMetadata, ...] = (
+    DocumentMetadata(
+        id="fomc_statement",
+        filename="01_fomc_statement_2025-09-17.html",
+        title="FOMC Statement — September 17, 2025",
+        description="Official statement outlining the Federal Reserve's policy decision and rationale.",
+    ),
+    DocumentMetadata(
+        id="implementation_note",
+        filename="02_implementation_note_2025-09-17.html",
+        title="Implementation Note — September 17, 2025",
+        description="Operational guidance on how the policy decision will be implemented across facilities.",
+    ),
+    DocumentMetadata(
+        id="sep_tables_pdf",
+        filename="03_sep_tables_2025-09-17.pdf",
+        title="Summary of Economic Projections Tables (PDF)",
+        description="PDF tables summarising participants' projections for key economic indicators.",
+    ),
+    DocumentMetadata(
+        id="sep_tables_html",
+        filename="04_sep_tables_2025-09-17.html",
+        title="Summary of Economic Projections Tables (HTML)",
+        description="HTML tables summarising participants' projections for key economic indicators.",
+    ),
+    DocumentMetadata(
+        id="press_conference_transcript",
+        filename="05_press_conference_transcript_2025-09-17.pdf",
+        title="Press Conference Transcript — September 17, 2025",
+        description="Chair Powell's press conference transcript following the September 2025 FOMC meeting.",
+    ),
+    DocumentMetadata(
+        id="bls_cpi_august",
+        filename="06_bls_cpi_2025-08.html",
+        title="BLS Consumer Price Index — August 2025",
+        description="Consumer Price Index report providing the latest inflation readings.",
+    ),
+    DocumentMetadata(
+        id="bea_gdp_q2_second_estimate",
+        filename="07_bea_gdp_q2_2025_second_estimate.pdf",
+        title="BEA GDP Second Estimate — Q2 2025",
+        description="Bureau of Economic Analysis second estimate of GDP for the second quarter of 2025.",
+    ),
+    DocumentMetadata(
+        id="monetary_policy_report",
+        filename="08_fed_mpr_2025-06.pdf",
+        title="Monetary Policy Report — June 2025",
+        description="Semiannual Monetary Policy Report submitted to Congress in June 2025.",
+    ),
+)
+DOCUMENTS_BY_ID: dict[str, DocumentMetadata] = {doc.id: doc for doc in DOCUMENTS}
+
+DOCUMENTS_BY_FILENAME: dict[str, DocumentMetadata] = {_normalise(doc.filename): doc for doc in DOCUMENTS}
+
+DOCUMENTS_BY_STEM: dict[str, DocumentMetadata] = {_normalise(doc.stem): doc for doc in DOCUMENTS}
+
+DOCUMENTS_BY_SLUG: dict[str, DocumentMetadata] = {}
+for document in DOCUMENTS:
+    for candidate in {
+        document.id,
+        document.filename,
+        document.stem,
+        document.title,
+        document.description or "",
+    }:
+        if candidate:
+            DOCUMENTS_BY_SLUG.setdefault(_slugify(candidate), document)
+
+
+def as_dicts(documents: Iterable[DocumentMetadata]) -> list[dict[str, str | None]]:
+    return [asdict(document) for document in documents]