AI: streaming-safe middleware, agent-driven Runner, ModelBuilder tool binding

.gitignore

@@ -1,6 +1,7 @@
 .idea
 .DS_Store
 **/.venv
+**/node_modules/
 **/__pycache__/
 **/*.db
 **/*.sqlite3

example/agents/.ai/fastapi-startkit/fastapi/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: fastapi-startkit
+description: Routing, controllers, ORM, requests, resources, and action pattern for fastapi-startkit applications.
+---
+
+# Fastapi's Routing
+
+### Fastapi Startkit's Router
+```python
+# routes/web.py
+from fastapi_startkit.fastapi import Router
+
+router = Router()
+```
+
+and use the crud resources, for example
+```python
+router.post("/users", users_controller.store)
+router.put("/users/{user_id}", users_controller.update)
+router.patch("/users/{user_id}", users_controller.patch)
+router.delete("/users", users_controller.destroy)
+```
+
+the controller will look like
+```python
+# app/http/controllers/users_controller.py
+async def index(request: Request):
+    pass
+
+async def show(user_id: int):
+    pass
+
+async def store(data: UserSchema):
+    pass
+
+async def update(user_id: int, data: UserSchema):
+    pass
+
+async def destroy(user_id: int):
+    pass
+```
+
+or use the resource function as:
+```python
+router.resource("users", users_controller, excepts=['create', 'edit'])
+```
+
+## ORM
+```python
+# app/models/user.py
+from fastapi_startkit.masoniteorm import Model
+
+class User(Model):
+    id: int
+    name: str
+    email: str
+    metadata: dict
+```
+
+and use the orm as:
+```python
+# app/http/controllers/users_controller.py
+from app.models import User
+
+async def store(request: UserStoreRequest):
+    user = User.create(request.model_dump())
+    ...
+```
+
+the `UserStoreRequest` will look like:
+```python
+# app/http/requests/user_store_request.py
+from pydantic import BaseModel
+
+class UserStoreRequest(BaseModel):
+    name: str
+```
+
+and use JsonApiResource to return JSON response from the controller:
+```python
+from fastapi_startkit.jsonapi import JsonResource
+
+# app/http/controllers/users_controller.py
+from app.models import User
+
+async def store(request: UserStoreRequest):
+    user = User.create(request.model_dump())
+    return JsonResource(user)
+```
+
+## Architecture
+
+use the action pattern to write complex logic.
+```python
+# app/actions/user_actions.py
+from app.models import User
+
+class UserStoreAction:
+    def __init__(self, request: UserStoreRequest):
+        self.request = request
+
+    @staticmethod
+    def prepare(request: UserStoreRequest) -> 'UserStoreAction':
+        return UserStoreAction(request)
+
+    def handle(self) -> JsonResource[User]:
+        user = User.create(self.request.model_dump())
+        return JsonResource(user)
+```

example/agents/.env.example

@@ -0,0 +1,5 @@
+APP_ENV=local
+APP_URL=http://127.0.0.1:7654
+
+AI_PROVIDER=google
+GEMINI_API_KEY=

example/agents/.github/workflows/lint.yml

@@ -0,0 +1,31 @@
+name: Lint
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: ["**"]
+
+jobs:
+  ruff:
+    name: Ruff
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run ruff check
+        run: uv run ruff check .
+
+      - name: Run ruff format check
+        run: uv run ruff format --check .

example/agents/.github/workflows/test.yml

@@ -0,0 +1,37 @@
+name: Test
+
+on:
+  pull_request:
+    branches: ["**"]
+
+jobs:
+  tests:
+    name: Pytest
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run tests
+        shell: bash
+        run: |
+          set +e
+          uv run pytest tests/ -v
+          code=$?
+          # Exit code 5 means "no tests collected" — treat as success so the
+          # starter template's CI stays green until real tests are added.
+          if [ "$code" -eq 5 ]; then
+            echo "No tests collected — treating as success."
+            exit 0
+          fi
+          exit $code

example/agents/.gitignore

@@ -0,0 +1,6 @@
+.idea
+.DS_Store
+.venv
+**__pycache__
+storage
+.env

example/agents/app/agents/chat.py

@@ -0,0 +1,17 @@
+from typing import Callable
+
+from fastapi_startkit.ai import Agent, Middleware
+
+from app.middleware.agent_logger import AgentLogger
+from app.tools.job_search_tool import job_search_tool
+
+
+class RouterAgent(Agent):
+    def middleware(self) -> list[Middleware]:
+        return [AgentLogger()]
+
+    def tools(self) -> list[Callable]:
+        return [job_search_tool]
+
+    def instructions(self) -> str:
+        return "You are a friendly customer support assistant."

example/agents/app/middleware/agent_logger.py

@@ -0,0 +1,25 @@
+import time
+from collections.abc import Callable
+from typing import Any
+
+from langchain_core.language_models.chat_models import BaseChatModel
+
+from fastapi_startkit.logging import Logger
+
+
+def _model_name(model: BaseChatModel) -> str:
+    return getattr(model, "model", None) or getattr(model, "model_name", None) or type(model).__name__
+
+
+class AgentLogger:
+    def handle(self, model: BaseChatModel, handler: Callable) -> Any:
+        Logger.info(f"request | model={_model_name(model)}")
+        started_at = time.monotonic()
+
+        def log_response(final: Any) -> None:
+            elapsed = time.monotonic() - started_at
+            meta = getattr(final, "usage_metadata", None) or {}
+            preview = str(getattr(final, "content", final) or "")[:200].replace("\n", " ")
+            Logger.info(f"response | {elapsed:.2f}s | in={meta.get('input_tokens', '?')} out={meta.get('output_tokens', '?')} tokens | {preview}")
+
+        return handler(model).then(log_response)

example/agents/app/providers/fastapi_provider.py

@@ -0,0 +1,13 @@
+from fastapi_startkit.fastapi import FastAPIProvider as BaseFastAPIProvider
+from fastapi.templating import Jinja2Templates
+
+
+class FastapiProvider(BaseFastAPIProvider):
+    def boot(self):
+        templates_dir = self.app.use_base_path("resources/templates")
+        self.app.bind("templates", Jinja2Templates(directory=str(templates_dir)))
+
+        super().boot()
+        from routes.api import api
+
+        self.app.fastapi.include_router(api)

example/agents/app/requests/chat.py

@@ -0,0 +1,5 @@
+from pydantic import BaseModel, Field
+
+
+class ChatRequest(BaseModel):
+    message: str = Field(...)

example/agents/app/schema/route.py

@@ -0,0 +1,8 @@
+from enum import StrEnum
+
+from pydantic import BaseModel
+
+
+class Route(StrEnum):
+    JOB_SEARCH: str
+    CHAT: str

example/agents/app/tools/job_search_tool.py

@@ -0,0 +1,25 @@
+from langchain_core.tools import tool
+
+jobs = [
+    {"id": 1, "title": "Software Engineer", "location": "San Francisco", "company": "Acme Corp", "type": "Full-time"},
+    {"id": 2, "title": "Frontend Developer", "location": "Remote", "company": "Startup Inc", "type": "Full-time"},
+    {"id": 3, "title": "Data Scientist", "location": "New York", "company": "DataCo", "type": "Full-time"},
+    {"id": 4, "title": "DevOps Engineer", "location": "Austin", "company": "CloudBase", "type": "Contract"},
+    {"id": 5, "title": "Product Manager", "location": "Remote", "company": "ProductHQ", "type": "Full-time"},
+]
+
+
+@tool
+def job_search_tool(query: str) -> list:
+    """Searches for jobs based on the given query. Supports wildcards (* and ?) in each term."""
+    import fnmatch
+
+    patterns = [f"*{term}*" for term in query.lower().split()]
+
+    return [
+        job for job in jobs
+        if any(
+            fnmatch.fnmatch(" ".join(str(v) for v in job.values()).lower(), pattern)
+            for pattern in patterns
+        )
+    ]

example/agents/artisan

@@ -0,0 +1,9 @@
+#!/usr/bin/env python3
+
+import sys
+
+from bootstrap.application import app
+
+if __name__ == "__main__":
+    status = app.handle_command()
+    sys.exit(status if isinstance(status, int) else 0)

example/agents/bootstrap/application.py

@@ -0,0 +1,25 @@
+from pathlib import Path
+
+from fastapi_startkit import Application
+from fastapi_startkit.inertia import InertiaProvider
+from fastapi_startkit.logging import LogProvider
+from fastapi_startkit.skills import AISkillProvider
+from fastapi_startkit.vite import ViteProvider
+from fastapi_startkit.ai import AIProvider
+
+from config.fastapi import FastAPIConfig
+from config.logging import LoggingConfig
+from config.vite import ViteConfig
+from app.providers.fastapi_provider import FastapiProvider
+
+app: Application = Application(
+    base_path=Path(__file__).resolve().parent.parent,
+    providers=[
+        AISkillProvider,
+        (LogProvider,LoggingConfig),
+        (FastapiProvider, FastAPIConfig),
+        AIProvider,
+        (ViteProvider, ViteConfig),
+        InertiaProvider,
+    ],
+)

example/agents/config/fastapi.py

@@ -0,0 +1,18 @@
+import dataclasses
+
+from fastapi_startkit.environment import env
+
+
+@dataclasses.dataclass
+class FastAPIConfig:
+    app_url: str = dataclasses.field(default_factory=lambda: env("APP_URL", "http://127.0.0.1:8000"))
+    reload: bool = dataclasses.field(default_factory=lambda: env("APP_RELOAD", True))
+    reload_dirs: list | None = None
+    reload_excludes: list = dataclasses.field(
+        default_factory=lambda: [
+            "*.log",
+            "tests/*",
+            "node_modules/*",
+            "storage/*",
+        ]
+    )

example/agents/config/logging.py

@@ -0,0 +1,22 @@
+import dataclasses
+
+from fastapi_startkit.environment import env
+from fastapi_startkit.logging.config import StackChannel, DailyChannel, TerminalChannel
+
+
+@dataclasses.dataclass
+class LoggingConfig:
+    default: str = dataclasses.field(default_factory=lambda: env("LOG_CHANNEL", "stack"))
+
+    channels: dict = dataclasses.field(
+        default_factory=lambda: {
+            "stack": StackChannel(driver="stack", channels=["daily", "terminal"]),
+            "daily": DailyChannel(
+                level=env("LOG_DAILY_LEVEL", "debug"),
+                path=env("LOG_DAILY_PATH", "storage/logs"),
+            ),
+            "terminal": TerminalChannel(
+                level=env("LOG_TERMINAL_LEVEL", "info"),
+            ),
+        }
+    )

example/agents/config/vite.py

@@ -0,0 +1,12 @@
+from pydantic.dataclasses import dataclass
+
+
+@dataclass
+class ViteConfig:
+    public_path: str = "public"
+    build_directory: str = "build"
+    hot_file: str = "hot"
+    manifest_filename: str = "manifest.json"
+    asset_url: str = ""
+    static_url: str = "/build"
+    mount_static: bool = True