Merge pull request #9 from mdrideout/nov_2025_updates

chore: release 0.62.1 (AI Chat example update)

Author: mdrideout

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to Junjo will be documented in this file.
 
+## 0.62.1 - 2026-02-14
+
+This patch release focuses on updates to the AI Chat example.
+
+### Changed
+
+- Restored direct Gemini node usage across `examples/ai_chat` workflows instead of routing through provider abstractions.
+- Standardized Gemini model usage to `gemini-3-flash-preview` for text/schema generation and `gemini-2.5-flash-image` for image generation/editing flows.
+- Hardened Gemini schema request handling for empty/blocked responses and max-token edge cases.
+- Updated `examples/ai_chat/README.md` and backend `.env.example` so Gemini is the default path with Grok as an optional experimentation path.
+
 ## 0.62.0 - 2026-02-08
 
 This release is primarily a cleanup and polish pass across existing features.
@@ -39,4 +50,3 @@ and intentionally diverges from Junjo AI Studio version numbering.
 
 - This is mostly non-feature cleanup/polish, but consumers importing removed internal modules will need to migrate imports.
 - Example projects changed substantially; treat `examples/ai_chat` as an updated reference implementation rather than a drop-in patch.
-

examples/ai_chat/README.md

@@ -14,9 +14,15 @@ This is a more complete example of Junjo, showcasing:
 
 ## AI provider
 
-This example is currently wired up to use **xAI (Grok)** for text + image generation (via `GrokTool`).
+This example is currently wired up to use **Gemini** for all workflow AI calls via `GeminiTool`.
 
-If you'd rather use **Gemini**, you can swap the workflow nodes to use `GeminiTool` instead (both live in `backend/src/app/ai_services/`).
+Current node defaults:
+
+- Text generation / structured output: `gemini-3-flash-preview`
+- Image generation / image edit: `gemini-2.5-flash-image`
+
+For experimentation, you can switch specific nodes to `GrokTool` (or back) by editing the tool import and model in
+the node files under `backend/src/app/workflows/`.
 
 ## Run the example
 

examples/ai_chat/backend/.env.example

@@ -1,11 +1,13 @@
 # Create your Junjo AI Studio API Key inside Junjo Studio
 JUNJO_AI_STUDIO_API_KEY="[junjo_ai_studio_api_key_here]"
 
-# xAI is the currently setup provider of chat and image generation responses. 
-XAI_API_KEY="[xai_api_key_here]"
-
-# Junjo nodes can be configured to use GeminiTool instead of GrokTool
+# Current default implementation in workflow nodes uses GeminiTool with:
+# - text/schema model: gemini-3-flash-preview
+# - image model: gemini-2.5-flash-image
 GEMINI_API_KEY="[gemini_api_key_here]"
 
-# Required by xAI SDK to produce opentelemetry
-OTEL_EXPORTER_OTLP_PROTOCOL="grpc"
+# Optional for experimentation if you switch any nodes to GrokTool
+XAI_API_KEY="[xai_api_key_here]"
+
+# Required by xAI SDK OTEL setup in app/otel_config.py (used when GrokTool is enabled)
+OTEL_EXPORTER_OTLP_PROTOCOL="grpc"

examples/ai_chat/backend/src/app/ai_services/gemini/gemini_tool.py

@@ -207,27 +207,46 @@ async def schema_request(self, schema: type[T]) -> T:
         logger.info(f"Making schema request with prompt: {self._prompt}")
 
         logger.debug(f"Making schema request with model: {self._model}, prompt: {self._prompt}, schema: {schema}")
-        response = await self._client.aio.models.generate_content(
-            model=self._model,
-            contents=self._prompt,
-            config=types.GenerateContentConfig(
-                max_output_tokens=500,
-                temperature=2,
-                response_mime_type="application/json",
-                response_schema=schema,
-                safety_settings=self._safety_settings_off(),
-            ),
-        )
-        logger.info(f"Raw response: {response}")
 
-        schema_response = response.parsed
-        if schema_response is None:
-            logger.error(f"Parsed schema response is None: {response}")
+        for attempt, max_output_tokens in enumerate((1024, 2048), start=1):
+            config_kwargs: dict[str, Any] = {
+                "max_output_tokens": max_output_tokens,
+                "temperature": 0,
+                "response_mime_type": "application/json",
+                "response_schema": schema,
+                "safety_settings": self._safety_settings_off(),
+            }
+            if hasattr(types, "ThinkingConfig"):
+                config_kwargs["thinking_config"] = types.ThinkingConfig(thinking_budget=0)
+
+            response = await self._client.aio.models.generate_content(
+                model=self._model,
+                contents=self._prompt,
+                config=types.GenerateContentConfig(**config_kwargs),
+            )
+            logger.info(f"Raw response (schema attempt {attempt}): {response}")
+
+            schema_response = response.parsed
+            if schema_response is not None:
+                return schema.model_validate(schema_response)
+
+            raw_text = (response.text or "").strip()
+            if raw_text:
+                try:
+                    return schema.model_validate_json(raw_text)
+                except Exception:
+                    logger.warning(f"Failed JSON fallback parsing on schema attempt {attempt}.")
 
-        # Validate again using the provided model
-        validated = schema.model_validate(schema_response)
+            finish_reason = None
+            if response.candidates:
+                finish_reason = response.candidates[0].finish_reason
+
+            logger.warning(
+                f"Parsed schema response is None on attempt {attempt}. "
+                f"finish_reason={finish_reason}, max_output_tokens={max_output_tokens}"
+            )
 
-        return validated
+        raise ValueError("Gemini schema_request failed: parsed response was None after retries.")
 
     async def gemini_image_request(self) -> bytes:
         """

examples/ai_chat/backend/src/app/workflows/create_contact/avatar_subflow/nodes/avatar_inspiration/node.py

@@ -1,7 +1,7 @@
 from junjo.node import Node
 from loguru import logger
 
-from app.ai_services.grok import GrokTool
+from app.ai_services.gemini.gemini_tool import GeminiTool
 from app.workflows.create_contact.avatar_subflow.nodes.avatar_inspiration.prompt import avatar_inspiration_prompt
 from app.workflows.create_contact.avatar_subflow.store import AvatarSubflowStore
 
@@ -46,11 +46,11 @@ async def service(self, store: AvatarSubflowStore) -> None:
         )
         logger.info(f"Creating response with prompt: {prompt}")
 
-        grok_tool = GrokTool(prompt=prompt, model="grok-4-1-fast-non-reasoning")
-        grok_result = await grok_tool.text_request()
-        logger.info(f"Grok result: {grok_result}")
+        gemini_tool = GeminiTool(prompt=prompt, model="gemini-3-flash-preview")
+        gemini_result = await gemini_tool.text_request()
+        logger.info(f"Gemini result: {gemini_result}")
 
         # Update the state with the avatar id
-        await store.set_inspiration_prompt(grok_result)
+        await store.set_inspiration_prompt(gemini_result)
 
         return

examples/ai_chat/backend/src/app/workflows/create_contact/avatar_subflow/nodes/create_avatar/node.py

@@ -2,7 +2,7 @@
 from loguru import logger
 from nanoid import generate
 
-from app.ai_services.grok import GrokTool
+from app.ai_services.gemini.gemini_tool import GeminiTool
 from app.util.save_image_file import save_image_file
 from app.workflows.create_contact.avatar_subflow.nodes.create_avatar.prompt import create_avatar_prompt
 from app.workflows.create_contact.avatar_subflow.store import AvatarSubflowStore
@@ -51,9 +51,9 @@ async def service(self, store: AvatarSubflowStore) -> None:
         )
         logger.info(f"Creating image with prompt: {prompt}")
 
-        grok_tool = GrokTool(prompt=prompt, model="grok-imagine-image")
-        image_bytes = await grok_tool.image_request()
-        logger.info(f"Grok result image size: {len(image_bytes) / 1024} kb")
+        gemini_tool = GeminiTool(prompt=prompt, model="gemini-2.5-flash-image")
+        image_bytes = await gemini_tool.gemini_image_request()
+        logger.info(f"Gemini result image size: {len(image_bytes) / 1024} kb")
 
         # Create an id for the avatar
         avatar_id = generate()

examples/ai_chat/backend/src/app/workflows/create_contact/nodes/create_bio/node.py

@@ -1,7 +1,7 @@
 from junjo.node import Node
 from loguru import logger
 
-from app.ai_services.grok import GrokTool
+from app.ai_services.gemini.gemini_tool import GeminiTool
 from app.workflows.create_contact.nodes.create_bio.prompt import create_bio_prompt
 from app.workflows.create_contact.store import CreateContactStore
 
@@ -38,11 +38,11 @@ async def service(self, store: CreateContactStore) -> None:
         )
         logger.info(f"Creating response with prompt: {prompt}")
 
-        grok_tool = GrokTool(prompt=prompt, model="grok-4-1-fast-non-reasoning")
-        grok_result = await grok_tool.text_request()
-        logger.info(f"Grok result: {grok_result}")
+        gemini_tool = GeminiTool(prompt=prompt, model="gemini-3-flash-preview")
+        gemini_result = await gemini_tool.text_request()
+        logger.info(f"Gemini result: {gemini_result}")
 
         # Update the state with the bio
-        await store.set_bio(grok_result)
+        await store.set_bio(gemini_result)
 
         return

examples/ai_chat/backend/src/app/workflows/create_contact/nodes/create_bio/test/test_service.py

@@ -1,4 +1,4 @@
-from app.ai_services.grok import GrokTool
+from app.ai_services.gemini.gemini_tool import GeminiTool
 from app.workflows.create_contact.nodes.create_bio.test.test_prompt import test_evaluate_bio_prompt
 from app.workflows.create_contact.nodes.create_bio.test.test_schema import TestCreateBioSchema
 
@@ -9,7 +9,7 @@ async def eval_create_bio_node(bio: str) -> TestCreateBioSchema:
     # Create the request to gemini for avatar inspiration
     prompt = test_evaluate_bio_prompt(bio)
 
-    grok_tool = GrokTool(prompt=prompt, model="grok-4-1-fast-non-reasoning")
-    grok_result = await grok_tool.schema_request(schema=TestCreateBioSchema)
+    gemini_tool = GeminiTool(prompt=prompt, model="gemini-3-flash-preview")
+    gemini_result = await gemini_tool.schema_request(schema=TestCreateBioSchema)
 
-    return grok_result
+    return gemini_result

examples/ai_chat/backend/src/app/workflows/create_contact/nodes/create_name/node.py

@@ -1,7 +1,7 @@
 from junjo.node import Node
 from loguru import logger
 
-from app.ai_services.grok import GrokTool
+from app.ai_services.gemini.gemini_tool import GeminiTool
 from app.workflows.create_contact.nodes.create_name.prompt import create_name_prompt
 from app.workflows.create_contact.nodes.create_name.schema import CreateNameSchema
 from app.workflows.create_contact.store import CreateContactStore
@@ -39,12 +39,12 @@ async def service(self, store: CreateContactStore) -> None:
         )
         logger.info(f"Creating response with prompt: {prompt}")
 
-        grok_tool = GrokTool(prompt=prompt, model="grok-4-1-fast-non-reasoning")
-        grok_result = await grok_tool.schema_request(CreateNameSchema)
-        logger.info(f"Grok result: {grok_result}")
+        gemini_tool = GeminiTool(prompt=prompt, model="gemini-3-flash-preview")
+        gemini_result = await gemini_tool.schema_request(CreateNameSchema)
+        logger.info(f"Gemini result: {gemini_result}")
 
         # Update the state with the first name
-        await store.set_first_name(grok_result.first_name)
-        await store.set_last_name(grok_result.last_name)
+        await store.set_first_name(gemini_result.first_name)
+        await store.set_last_name(gemini_result.last_name)
 
         return

examples/ai_chat/backend/src/app/workflows/create_contact/nodes/select_location/services/get_nearest_city_state.py

@@ -1,6 +1,6 @@
 from loguru import logger
 
-from app.ai_services.grok import GrokTool
+from app.ai_services.gemini.gemini_tool import GeminiTool
 from app.workflows.create_contact.nodes.select_location.schemas import LocCityState
 from app.workflows.create_contact.nodes.select_location.services.get_nearest_city_state_prompt import (
     get_nearest_city_state_prompt,
@@ -16,8 +16,8 @@ async def get_nearest_city_state(lat: float, long: float) -> LocCityState:
     prompt = get_nearest_city_state_prompt(lat, long)
     logger.info(f"Creating response with prompt: {prompt}")
 
-    grok_tool = GrokTool(prompt=prompt, model="grok-4-1-fast-non-reasoning")
-    grok_result = await grok_tool.schema_request(schema=LocCityState)
-    logger.info(f"Grok result: {grok_result}")
+    gemini_tool = GeminiTool(prompt=prompt, model="gemini-3-flash-preview")
+    gemini_result = await gemini_tool.schema_request(schema=LocCityState)
+    logger.info(f"Gemini result: {gemini_result}")
 
-    return grok_result
+    return gemini_result