fix(agent): improve ADK setup logic (flare-foundation#104)

Author: dineshpinto

.env.example

@@ -43,7 +43,6 @@ GCP__TAGS=flare-ai,http-server,https-server
 
 # API key for using Google Gemini (https://aistudio.google.com/app/apikey).
 AGENT__GEMINI_API_KEY="your_api_key"
-GOOGLE_API_KEY="your_api_key"
 
 # Gemini model to use (e.g. gemini-2.5-flash, gemini-2.5-pro)
 # AGENT__GEMINI_MODEL="gemini-2.5-flash"

README.md

@@ -1,21 +1,21 @@
 # Flare AI Kit
 
-SDK for building **verifiable AI Agents** on Flare using Confidential Space.
+SDK for building **verifiable AI Agents** on Flare using Confidential Space Trusted Execution Environments (TEEs).
 
 > [!WARNING]
 >
-> Flare AI Kit is currently under active development (pre-release/alpha stage).
+> Flare AI Kit is currently under active development (alpha stage).
 >
 > Interfaces, APIs, and functionalities may change frequently and potentially in backward-incompatible ways before a stable release.
 > Use with caution.
 
 ## ✨ Features
 
-- **Verifiable Execution**: Run logic in hardware‑isolated TEEs - [GCP Confidential Space TDX](https://cloud.google.com/confidential-computing/confidential-space/docs/confidential-space-overview).
-- **Consensus Engine**: Multi‑agent [Consensus Learning](https://arxiv.org/abs/2402.16157) via [Google Agent2Agent](https://github.com/a2aproject/A2A) protocol.
-- **Strictly‑Typed Agents**: Build with [PydanticAI](https://ai.pydantic.dev) to enforce structured outputs across 200+ LLMs.
-- **Flare Protocol Integration**: [FTSO](https://dev.flare.network/ftso/overview), [FDC](https://dev.flare.network/fdc/overview), [FAssets](https://dev.flare.network/fassets/overview), plus ecosystem dApps like [Sceptre](http://sceptre.fi) and [SparkDEX](https://sparkdex.ai).
-- **Social Intelligence**: Analytics and connectors for X, Telegram, Farcaster.
+- **Verifiable execution**: Run logic inside Intel TDX TEEs via [GCP Confidential Space](https://cloud.google.com/confidential-computing/confidential-space/docs/confidential-space-overview).
+- **Multi-agent consensus**: Majority/Tournament/[Consensus Learning](https://arxiv.org/abs/2402.16157) via [Google Agent2Agent](https://github.com/a2aproject/A2A) protocol.
+- **Agent framework**: Built on [Google ADK](https://google.github.io/adk-docs/) with tool-calling, orchestration and evaluation.
+- **Flare integration**: [FTSO](https://dev.flare.network/ftso/overview), [FDC](https://dev.flare.network/fdc/overview), [FAssets](https://dev.flare.network/fassets/overview) + ecosystem dApps ([Sceptre](https://sceptre.fi), [SparkDEX](https://sparkdex.ai), ...).
+- **Social connectors**: X, Telegram, Farcaster.
 
 ## 🏗️ Architecture
 
@@ -80,22 +80,17 @@ flowchart TD
 
 - [uv](https://github.com/astral-sh/uv) with Python >= 3.12
 - [Docker](https://www.docker.com).
+- (For deployment) Authenticated [gcloud CLI](https://cloud.google.com/sdk/docs/install).
 
-1. **Clone the repo:**
+1. **Clone & configure:**
 
    ```bash
    git clone --recursive https://github.com/flare-foundation/flare-ai-kit.git
    cd flare-ai-kit
+   cp .env.example .env  # add API keys and settings
    ```
 
-2. **Configure your environment:**
-
-   ```bash
-   # Copy the template and add your models, API keys etc.
-   cp .env.example .env
-   ```
-
-3. **Install dependencies:**
+2. **Install:**
 
    ```bash
    uv sync --all-extras
@@ -106,22 +101,15 @@ flowchart TD
 Run the following commands to format, lint, type-check, and test your code before committing.
 
 ```bash
-# Format, lint, and auto-fix
-uv run ruff format
-uv run ruff check --fix
-
-# Run static type checking
-uv run pyright
-
-# Run tests
-uv run pytest
+# Format, lint, type-check, test
+uv run ruff format && uv run ruff check --fix && uv run pyright && uv run pytest
 ```
 
-## 🚧 Build with Docker
+## 🐳 Docker
 
 ```bash
 docker build -t flare-ai-kit .
-docker run -rm --env-file .env flare-ai-kit
+docker run --rm --env-file .env flare-ai-kit
 ```
 
 ## ☁️ Deploy to Confidential Space
@@ -134,12 +122,14 @@ docker run -rm --env-file .env flare-ai-kit
 
    ```bash
    chmod +x gcloud-deploy.sh
-   ./gcloud-deploy.sh # For verbose mode: ./gcloud-deploy.sh -v
+   ./gcloud-deploy.sh # verbose: ./gcloud-deploy.sh -v
    ```
 
 ## 🤝 Contributing
 
-Contributions are highly encouraged! Please review the [CONTRIBUTING.md](CONTRIBUTING.md) guide for details on code style (Conventional Commits, Strict Typing), testing, and the PR process.
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+We use Conventional Commits, Ruff/Pyright gates, and pytest.
+Please include tests and update docs for any user-visible changes.
 
 ## 📜 License
 

examples/05_ingest_pdf.py

@@ -2,18 +2,20 @@
 
 import asyncio
 import json
+import os
 import re
 from pathlib import Path
 from typing import Any
 from unittest.mock import AsyncMock, mock_open, patch
 
 from data.create_sample_invoice import create_invoice_and_build_template
+from google.adk.agents import Agent
 from google.adk.runners import Runner
 from google.adk.sessions import InMemorySessionService
 from google.genai import types
 
 from flare_ai_kit import FlareAIKit
-from flare_ai_kit.agent.adk_agent import pdf_agent
+from flare_ai_kit.agent.pdf_tools import read_pdf_text_tool
 from flare_ai_kit.config import AppSettings
 from flare_ai_kit.ingestion.settings import (
     IngestionSettings,
@@ -55,18 +57,22 @@ def _json_from(text: str) -> dict[str, Any]:
 
 
 async def parse_pdf_to_template_json(
-    pdf: str | Path, template: PDFTemplateSettings, max_pages: int | None = None
+    agent: Agent,
+    pdf: str | Path,
+    template: PDFTemplateSettings,
+    max_pages: int | None = None,
 ) -> dict[str, Any]:
     """Setup in-memory ADK agent, give it the PDF, template and prompt."""
     pdf = Path(pdf)
     svc = InMemorySessionService()
     await svc.create_session(app_name="app", user_id="u", session_id="s")
-    runner = Runner(agent=pdf_agent, app_name="app", session_service=svc)
+    runner = Runner(agent=agent, app_name="app", session_service=svc)
 
     msg = types.Content(
         role="user", parts=[types.Part(text=_prompt(pdf, template, max_pages))]
     )
     final_text = None
+    print(f"Calling {agent.name} using model: {agent.model}")
     async for ev in runner.run_async(user_id="u", session_id="s", new_message=msg):
         if ev.is_final_response() and ev.content and ev.content.parts:
             final_text = ev.content.parts[0].text
@@ -97,6 +103,33 @@ async def main() -> None:
         ),
     )
 
+    # Inject Gemini API Key
+    if app_settings.agent and app_settings.agent.gemini_api_key:
+        api_key = app_settings.agent.gemini_api_key.get_secret_value()
+        os.environ["GOOGLE_API_KEY"] = api_key
+
+    # Create ADK agent with tool access.
+    pdf_agent_instruction = (
+        "You are a PDF extraction agent. "
+        "Independently read PDFs using tools and return ONLY JSON matching this schema:\n"
+        "{\n"
+        '  "template_name": string,\n'
+        '  "fields": [ {"field_name": string, "value": string|null}, ... ]\n'
+        "}\n"
+        "- Always call read_pdf_text with the provided file path.\n"
+        "- Use ONLY the template JSON (field order and names) provided by the user to decide what to extract.\n"
+        "- If a field is not found, set its value to null.\n"
+        "- Do not include prose or explanations. Reply with a single JSON object only."
+    )
+
+    # Construct the Agent instance using the imported tool and settings
+    pdf_agent = Agent(
+        name="flare_pdf_agent",
+        model=app_settings.agent.gemini_model,
+        tools=[read_pdf_text_tool],
+        instruction=pdf_agent_instruction,
+    )
+
     # Mock onchain contract posting
     with (
         patch(
@@ -114,7 +147,9 @@ async def main() -> None:
         print("📄 extracted:", mock_post.call_args[0][0])
 
     # Agent PDF parsing
-    structured = await parse_pdf_to_template_json(pdf_path, template, max_pages=1)
+    structured = await parse_pdf_to_template_json(
+        pdf_agent, pdf_path, template, max_pages=1
+    )
     print("🧩 agent JSON:", json.dumps(structured, indent=2))
 
 

examples/02_rag_vector_demo.py examples/07_rag_vector_demo.pyexamples/02_rag_vector_demo.py renamed to examples/07_rag_vector_demo.py

@@ -105,7 +105,7 @@ ignore = ["D203", "D212", "COM812", "S105", "D401", "D104", "ANN401", "ISC003",
 "src/flare_ai_kit/agent/adk_agent.py" = ["E501"]
 "src/flare_ai_kit/agent/ecosystem_tools_wrapper.py" = ["PLC0415"]
 "tests/**/*.py" = ["S", "ARG", "PLR2004", "SLF001", "BLE001", "E501", "T201", "D", "ANN", "F821", "PLC"]
-"examples/**/*.py" = ["D", "T201", "BLE001", "INP001"]
+"examples/**/*.py" = ["D", "T201", "BLE001", "INP001", "E501"]
 
 [tool.pyright]
 pythonVersion = "3.12"

examples/data/examples/data/sample_invoice.pdf

@@ -1,3 +1,4 @@
 from .settings import AgentSettings
+from .tools import TOOL_REGISTRY
 
-__all__ = ["AgentSettings"]
+__all__ = ["TOOL_REGISTRY", "AgentSettings"]

pyproject.toml

@@ -0,0 +1,7 @@
+"""Module provides a single, shared instance of the Flare AI Kit SDK for agent."""
+
+from flare_ai_kit.main import FlareAIKit
+
+# This single `kit` instance will be imported and used by all agent tools.
+# It will be initialized once when the module is first imported.
+kit = FlareAIKit(config=None)