feat(v1.2): add Ollama tier-0 provider + OpenAPI 3.1 spec export

Phase 8 — Local Ollama Provider in maf_starter:
- Settings: ollama_base_url / ollama_model fields; api_key guard optional
  when OLLAMA_BASE_URL is set (fully offline, no GEMINI_API_KEY required)
- Fallback chain: ollama prepended at tier-0 when configured
- agent_factory: create_client() and build_agent() dispatch to Ollama
- provider_fallback: ollama branch in _execute_chain_step()
- routing_policy: _lane_default_chain() returns ollama primary when set;
  _gemini_fallbacks_for_tier() helper provides Gemini safety net
- maf_starter/cli.py: smoke sub-command (python main.py smoke)
- main.py: hybrid dispatch — smoke -> maf_starter.cli; else legacy path
- .env.example: Ollama/Gemma local-only config block added
- 5 new tests; all 20 tests green

Phase 9 — OpenAPI Spec + Promptimprover Local Config:
- autogen_dashboard/app.py: SSE endpoint annotated (summary, description)
- scripts/export_openapi.py: standalone spec export; no env vars required
- openapi.json: OpenAPI 3.1.0, 14 paths, 28 schemas
- requirements.txt: openapi-spec-validator>=0.7,<1.0 added

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Aitomates

.env.example

@@ -28,3 +28,8 @@ CLAUDE_CLI_MODEL=
 CLAUDE_CODE_GIT_BASH_PATH=
 CODEX_CLI_COMMAND=codex.cmd
 CODEX_CLI_MODEL=
+
+# Local Ollama / Gemma (fully offline, no GEMINI_API_KEY required)
+# Prerequisites: ollama pull gemma3 && ollama serve
+OLLAMA_BASE_URL=http://localhost:11434/v1
+OLLAMA_MODEL=gemma3

autogen_dashboard/app.py

@@ -192,7 +192,24 @@ async def api_retry(
         except ValueError as exc:
             raise HTTPException(status_code=400, detail=str(exc)) from exc
 
-    @app.get("/api/sessions/{session_id}/events")
+    @app.get(
+        "/api/sessions/{session_id}/events",
+        summary="Stream session events (SSE)",
+        description=(
+            "Server-Sent Events stream for the given session. "
+            "Each event frame carries a typed payload. "
+            "The first event is always a 'snapshot' containing the full current session state. "
+            "Subsequent events are incremental updates. "
+            "Media type: text/event-stream."
+        ),
+        responses={
+            200: {
+                "description": "SSE stream of session events",
+                "content": {"text/event-stream": {"schema": {"type": "string"}}},
+            },
+            404: {"description": "Session not found"},
+        },
+    )
     async def api_session_events(
         session_id: str,
         since_seq: int = 0,

maf_starter/agent_factory.py

@@ -12,6 +12,12 @@
 
 
 def create_client(settings: Settings, *, routing_mode: str = "auto"):
+    if settings.ollama_base_url:
+        return OpenAIChatClient(
+            model_id=settings.ollama_model,
+            api_key="ollama",
+            base_url=settings.ollama_base_url,
+        )
     return OpenAIChatClient(
         model_id=settings.model,
         api_key=settings.api_key,
@@ -49,8 +55,8 @@ def build_agent(
         middleware=[
             build_fallback_middleware(
                 current,
-                primary_provider="gemini",
-                primary_model=current.model,
+                primary_provider="ollama" if current.ollama_base_url else "gemini",
+                primary_model=current.ollama_model if current.ollama_base_url else current.model,
                 routing_mode=routing_mode,
             )
         ],

maf_starter/cli.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+
+from agent_framework import Message
+
+from maf_starter.agent_factory import create_client
+from maf_starter.config import load_settings
+
+
+DEFAULT_SMOKE_MESSAGE = "Reply with exactly: READY"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="maf", description="MAF starter CLI")
+    sub = parser.add_subparsers(dest="command")
+    sub.add_parser("smoke", help="Send a quick probe message to verify the configured provider responds")
+    return parser
+
+
+async def run_smoke() -> None:
+    settings = load_settings()
+    client = create_client(settings)
+    response = await client.get_response([Message(role="user", text=DEFAULT_SMOKE_MESSAGE)])
+    provider = "ollama" if settings.ollama_base_url else "gemini"
+    model = settings.ollama_model if settings.ollama_base_url else settings.model
+    print(f"[smoke] provider={provider} model={model}")
+    print(f"[smoke] response: {response.text.strip()}")
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+    if args.command == "smoke":
+        try:
+            asyncio.run(run_smoke())
+            return 0
+        except ValueError as exc:
+            print(f"[smoke] configuration error: {exc}", file=sys.stderr)
+            return 2
+        except Exception as exc:
+            print(f"[smoke] failed: {exc}", file=sys.stderr)
+            return 1
+    parser.print_help()
+    return 0

maf_starter/config.py

@@ -50,6 +50,8 @@ class Settings:
     codex_cli_command: str = "codex.cmd"
     codex_cli_model: str | None = None
     model_candidates: tuple[str, ...] = DEFAULT_MODEL_CANDIDATES
+    ollama_base_url: str | None = None
+    ollama_model: str = "gemma3"
 
     def with_run_scope(
         self,
@@ -110,14 +112,22 @@ def _split_candidates(raw_value: str | None) -> tuple[str, ...]:
     return values or DEFAULT_MODEL_CANDIDATES
 
 
-def _default_fallback_chain(*, anthropic_model: str | None, anthropic_api_key: str | None) -> tuple[str, ...]:
+def _default_fallback_chain(
+    *,
+    anthropic_model: str | None,
+    anthropic_api_key: str | None,
+    ollama_base_url: str | None = None,
+    ollama_model: str = "gemma3",
+) -> tuple[str, ...]:
     chain: list[str] = [
         "gemini:gemini-2.5-pro",
         "gemini:gemini-2.5-flash",
         "gemini:gemini-2.5-flash-lite",
     ]
     if anthropic_api_key:
         chain.insert(1, f"anthropic:{anthropic_model or DEFAULT_ANTHROPIC_MODEL}")
+    if ollama_base_url:
+        chain.insert(0, f"ollama:{ollama_model}")
     chain.extend(
         [
             "claude-cli",
@@ -133,11 +143,15 @@ def _split_fallback_chain(
     *,
     anthropic_model: str | None,
     anthropic_api_key: str | None,
+    ollama_base_url: str | None = None,
+    ollama_model: str = "gemma3",
 ) -> tuple[str, ...]:
     if not raw_value:
         return _default_fallback_chain(
             anthropic_model=anthropic_model,
             anthropic_api_key=anthropic_api_key,
+            ollama_base_url=ollama_base_url,
+            ollama_model=ollama_model,
         )
     values = tuple(part.strip() for part in raw_value.split(",") if part.strip())
     return values
@@ -185,8 +199,13 @@ def load_settings(*, env_path: Path | None = None, project_root: Path | None = N
         load_dotenv(dotenv_path=dotenv_path, override=False)
 
     api_key = (os.getenv("MAF_API_KEY") or os.getenv("GEMINI_API_KEY") or "").strip()
-    if not api_key:
-        raise ValueError("Set GEMINI_API_KEY or MAF_API_KEY in the repo .env file.")
+    ollama_base_url = (os.getenv("OLLAMA_BASE_URL") or "").strip() or None
+    ollama_model = (os.getenv("OLLAMA_MODEL") or "gemma3").strip()
+    if not api_key and not ollama_base_url:
+        raise ValueError(
+            "Set GEMINI_API_KEY or MAF_API_KEY in the repo .env file, "
+            "or set OLLAMA_BASE_URL for local-only operation."
+        )
 
     model = (os.getenv("MAF_MODEL") or os.getenv("GEMINI_MODEL") or DEFAULT_MODEL).strip()
     base_url = (os.getenv("MAF_BASE_URL") or os.getenv("GEMINI_BASE_URL") or DEFAULT_GEMINI_BASE_URL).strip()
@@ -215,7 +234,11 @@ def load_settings(*, env_path: Path | None = None, project_root: Path | None = N
             os.getenv("MAF_FALLBACK_CHAIN"),
             anthropic_model=anthropic_model,
             anthropic_api_key=anthropic_api_key,
+            ollama_base_url=ollama_base_url,
+            ollama_model=ollama_model,
         ),
+        ollama_base_url=ollama_base_url,
+        ollama_model=ollama_model,
         anthropic_api_key=anthropic_api_key,
         anthropic_model=anthropic_model or DEFAULT_ANTHROPIC_MODEL,
         gemini_cli_command=(os.getenv("GEMINI_CLI_COMMAND") or "gemini.cmd").strip(),

maf_starter/provider_fallback.py

@@ -446,6 +446,44 @@ async def _execute_chain_step(
             return _stream_from_response(response)
         return response
 
+    if step.provider == "ollama":
+        if not settings.ollama_base_url:
+            raise RuntimeError("Ollama base URL is not configured. Set OLLAMA_BASE_URL.")
+        client = OpenAIChatClient(
+            model_id=step.model or settings.ollama_model,
+            api_key="ollama",
+            base_url=settings.ollama_base_url,
+        )
+        if _context_is_streaming(context):
+            response = client.get_streaming_response(
+                context.messages,
+                **_context_response_kwargs(context, _override_model(context.options, step.model or settings.ollama_model)),
+            )
+        else:
+            response = await client.get_response(
+                context.messages,
+                **_context_response_kwargs(context, _override_model(context.options, step.model or settings.ollama_model)),
+            )
+        if attempt_log is not None:
+            attempt_log.append(
+                _build_route_attempt(
+                    step.provider,
+                    step.model or settings.ollama_model,
+                    status="succeeded",
+                    fallback_index=fallback_index,
+                    tools_available=True,
+                )
+            )
+        return _decorate_result(
+            response,
+            settings=settings,
+            step=step,
+            route=route,
+            prior_error=prior_error,
+            add_notice=False,
+            attempt_log=attempt_log,
+        )
+
     raise RuntimeError(f"Unsupported fallback provider: {step.provider}")
 
 

maf_starter/routing_policy.py

@@ -157,6 +157,10 @@ def _build_lane_chain(
 
 def _lane_default_chain(settings: Settings, *, lane: RouteLane, tier: str) -> tuple[ChainStep, tuple[ChainStep, ...]]:
     normalized_tier = tier if lane == "auto" else _tier_for_lane(lane)[0]
+    if settings.ollama_base_url:
+        ollama_primary = ChainStep("ollama", settings.ollama_model)
+        gemini_fallbacks = _gemini_fallbacks_for_tier(settings, normalized_tier)
+        return ollama_primary, gemini_fallbacks
     if normalized_tier == "simple":
         primary = ChainStep("gemini", "gemini-2.5-flash-lite")
         fallbacks = [
@@ -187,6 +191,23 @@ def _lane_default_chain(settings: Settings, *, lane: RouteLane, tier: str) -> tu
     return primary, tuple(fallbacks)
 
 
+def _gemini_fallbacks_for_tier(settings: Settings, tier: str) -> tuple[ChainStep, ...]:
+    if tier == "simple":
+        return (
+            ChainStep("gemini", "gemini-2.5-flash-lite"),
+            ChainStep("gemini", "gemini-2.5-flash"),
+        )
+    if tier == "deep":
+        return (
+            ChainStep("gemini", "gemini-2.5-pro"),
+            ChainStep("gemini", "gemini-2.5-flash"),
+        )
+    return (
+        ChainStep("gemini", "gemini-2.5-flash"),
+        ChainStep("gemini", "gemini-2.5-pro"),
+    )
+
+
 def _tier_for_lane(lane: RouteLane) -> tuple[str, str]:
     if lane == "deep":
         return "deep", "The deep lane was selected explicitly."

main.py

@@ -1,5 +1,15 @@
-from autogen_starter.cli import main
+from __future__ import annotations
+
+import sys
+
+
+def _dispatch() -> int:
+    if len(sys.argv) >= 2 and sys.argv[1] == "smoke":
+        from maf_starter.cli import main as maf_main
+        return maf_main()
+    from autogen_starter.cli import main as legacy_main
+    return legacy_main()
 
 
 if __name__ == "__main__":
-    raise SystemExit(main())
+    raise SystemExit(_dispatch())