keboola-cli 0.63.4__py3-none-any.whl

keboola_agent_cli/server/routers/flows.py

@@ -0,0 +1,204 @@
+"""Flow + flow-schedule endpoints (conditional flows / keboola.flow only)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from pydantic import BaseModel
+
+from ...services.flow_validation import find_unreachable_phases, validate_conditional_flow
+from ..dependencies import ServiceRegistry, get_registry
+
+router = APIRouter(prefix="/flows", tags=["flows"])
+
+
+class FlowCreate(BaseModel):
+    name: str
+    description: str = ""
+    phases: list[dict[str, Any]] | None = None
+    tasks: list[dict[str, Any]] | None = None
+    branch_id: int | None = None
+
+
+class FlowUpdate(BaseModel):
+    name: str | None = None
+    description: str | None = None
+    phases: list[dict[str, Any]] | None = None
+    tasks: list[dict[str, Any]] | None = None
+    branch_id: int | None = None
+
+
+class FlowSchedule(BaseModel):
+    cron_tab: str
+    timezone: str = "UTC"
+    enabled: bool = True
+    schedule_name: str | None = None
+    branch_id: int | None = None
+
+
+class FlowValidate(BaseModel):
+    phases: list[dict[str, Any]] = []
+    tasks: list[dict[str, Any]] = []
+    project: str | None = None
+
+
+# NOTE: /validate and /{project}/schema are declared BEFORE the /{project}
+# and /{project}/{config_id} routes -- FastAPI matches in declaration order,
+# so the literal segments must win over the path parameters.
+
+
+@router.post("/validate", summary="Validate a conditional-flow definition")
+def validate(
+    body: FlowValidate, registry: ServiceRegistry = Depends(get_registry)
+) -> dict[str, Any]:
+    """Validate phases/tasks (schema + semantic checks). Mirrors `kbagent flow validate`.
+
+    With ``project`` the live keboola.flow JSON Schema is fetched from the stack
+    for structural validation; a fetch failure degrades to semantic-only and is
+    recorded in ``notes``. Without ``project`` only semantic checks run.
+    """
+    schema: dict[str, Any] | None = None
+    notes: list[str] = []
+    if body.project:
+        fetch = registry.flow.fetch_flow_schema(body.project)
+        schema = fetch.schema
+        if schema is None:
+            notes.append(f"structural schema validation skipped: {fetch.reason}")
+    else:
+        notes.append(
+            "structural schema validation skipped: no schema source "
+            "(pass 'project' to fetch the live schema from the stack)"
+        )
+    errors = validate_conditional_flow(body.phases, body.tasks, schema)
+    warnings = [
+        f"Phase '{pid}' is unreachable from the entry phase"
+        for pid in find_unreachable_phases(body.phases)
+    ]
+    return {"valid": not errors, "errors": errors, "warnings": warnings, "notes": notes}
+
+
+@router.get("/{project}/schema", summary="Fetch the live conditional-flow JSON Schema")
+def get_schema(project: str, registry: ServiceRegistry = Depends(get_registry)) -> dict[str, Any]:
+    """Dump the keboola.flow JSON Schema served by the stack. Mirrors `kbagent flow schema --full`."""
+    fetch = registry.flow.fetch_flow_schema(project)
+    if fetch.schema is None:
+        raise HTTPException(
+            status_code=502,
+            detail=f"Could not fetch the conditional-flow schema: {fetch.reason}",
+        )
+    return {"format": "json-schema", "schema": fetch.schema}
+
+
+@router.get("", summary="List flows across projects")
+def list_flows(
+    project: list[str] | None = Query(None),
+    branch_id: int | None = None,
+    with_schedules: bool = False,
+    registry: ServiceRegistry = Depends(get_registry),
+) -> dict[str, Any]:
+    """List flows in one or more projects. Mirrors `kbagent flow list`."""
+    return registry.flow.list_flows(
+        aliases=project, branch_id=branch_id, with_schedules=with_schedules
+    )
+
+
+@router.get("/{project}/{config_id}", summary="Get flow detail")
+def detail(
+    project: str,
+    config_id: str,
+    branch_id: int | None = None,
+    registry: ServiceRegistry = Depends(get_registry),
+) -> dict[str, Any]:
+    """Fetch a single flow configuration. Mirrors `kbagent flow detail`."""
+    return registry.flow.get_flow_detail(alias=project, config_id=config_id, branch_id=branch_id)
+
+
+@router.post("/{project}", summary="Create a new flow")
+def create(
+    project: str, body: FlowCreate, registry: ServiceRegistry = Depends(get_registry)
+) -> dict[str, Any]:
+    """Create a new flow configuration. Mirrors `kbagent flow new`."""
+    return registry.flow.create_flow(
+        alias=project,
+        name=body.name,
+        description=body.description,
+        phases=body.phases,
+        tasks=body.tasks,
+        branch_id=body.branch_id,
+    )
+
+
+@router.patch("/{project}/{config_id}", summary="Update an existing flow")
+def update(
+    project: str,
+    config_id: str,
+    body: FlowUpdate,
+    registry: ServiceRegistry = Depends(get_registry),
+) -> dict[str, Any]:
+    """Update name, description, or phases/tasks of a flow. Mirrors `kbagent flow update`."""
+    return registry.flow.update_flow(
+        alias=project,
+        config_id=config_id,
+        name=body.name,
+        description=body.description,
+        phases=body.phases,
+        tasks=body.tasks,
+        branch_id=body.branch_id,
+    )
+
+
+@router.delete("/{project}/{config_id}", summary="Delete a flow")
+def delete(
+    project: str,
+    config_id: str,
+    branch_id: int | None = None,
+    registry: ServiceRegistry = Depends(get_registry),
+) -> dict[str, Any]:
+    """Delete a flow configuration. Mirrors `kbagent flow delete`."""
+    return registry.flow.delete_flow(alias=project, config_id=config_id, branch_id=branch_id)
+
+
+@router.get("/{project}/{config_id}/schedules", summary="List schedules for a flow")
+def list_schedules(
+    project: str,
+    config_id: str,
+    branch_id: int | None = None,
+    registry: ServiceRegistry = Depends(get_registry),
+) -> dict[str, Any]:
+    """List cron schedules attached to a flow."""
+    return registry.flow.list_flow_schedules(
+        alias=project, config_id=config_id, branch_id=branch_id
+    )
+
+
+@router.post("/{project}/{config_id}/schedule", summary="Set a cron schedule on a flow")
+def set_schedule(
+    project: str,
+    config_id: str,
+    body: FlowSchedule,
+    registry: ServiceRegistry = Depends(get_registry),
+) -> dict[str, Any]:
+    """Attach or update a cron schedule on a flow. Mirrors `kbagent flow schedule`."""
+    return registry.flow.set_flow_schedule(
+        alias=project,
+        config_id=config_id,
+        cron_tab=body.cron_tab,
+        timezone=body.timezone,
+        enabled=body.enabled,
+        schedule_name=body.schedule_name,
+        branch_id=body.branch_id,
+    )
+
+
+@router.delete("/{project}/{config_id}/schedule", summary="Remove a flow schedule")
+def remove_schedule(
+    project: str,
+    config_id: str,
+    branch_id: int | None = None,
+    registry: ServiceRegistry = Depends(get_registry),
+) -> dict[str, Any]:
+    """Remove the cron schedule from a flow. Mirrors `kbagent flow schedule-remove`."""
+    return registry.flow.remove_flow_schedule(
+        alias=project, config_id=config_id, branch_id=branch_id
+    )

keboola_agent_cli/server/routers/health.py

@@ -0,0 +1,53 @@
+"""Health, version, changelog, and doctor endpoints."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, Depends
+
+from ... import __version__
+from ...changelog import CHANGELOG, get_changelog
+from ..dependencies import ServiceRegistry, get_registry
+
+router = APIRouter(tags=["health"])
+
+
+@router.get("/health/ping", summary="Liveness check")
+def ping() -> dict[str, Any]:
+    """Unauthenticated liveness check."""
+    return {"status": "ok", "version": __version__}
+
+
+@router.get("/health/auth-info", summary="Show authentication scheme")
+def auth_info() -> dict[str, Any]:
+    """Public info about authentication scheme (no secrets disclosed)."""
+    return {
+        "scheme": "bearer",
+        "header": "Authorization",
+        "note": (
+            "Send 'Authorization: Bearer <token>'. The token is printed to "
+            "stdout when 'kbagent serve' starts."
+        ),
+    }
+
+
+@router.get("/version", summary="Show kbagent versions")
+def version(registry: ServiceRegistry = Depends(get_registry)) -> dict[str, Any]:
+    """Versions of kbagent, MCP server, and Python."""
+    return registry.version.get_versions()
+
+
+@router.get("/changelog", summary="List release notes")
+def changelog(limit: int | None = None) -> dict[str, Any]:
+    """Return release entries; pass ``?limit=N`` for the latest N."""
+    items = get_changelog(limit=limit) if limit is not None and limit > 0 else dict(CHANGELOG)
+    return {
+        "entries": [{"version": v, "highlights": notes} for v, notes in items.items()],
+    }
+
+
+@router.get("/doctor", summary="Run health diagnostics")
+def doctor(registry: ServiceRegistry = Depends(get_registry)) -> dict[str, Any]:
+    """Run kbagent doctor health checks."""
+    return registry.doctor.run_checks()

keboola_agent_cli/server/routers/jobs.py

@@ -0,0 +1,175 @@
+"""Job endpoints (list, detail, run, terminate) + SSE log/status streaming."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+from typing import Any
+
+from fastapi import APIRouter, Depends, Query
+from pydantic import BaseModel
+from sse_starlette.sse import EventSourceResponse
+
+from ...constants import DEFAULT_JOB_MODE, DEFAULT_LOG_TAIL_LINES, DEFAULT_POLL_STRATEGY
+from ..dependencies import ServiceRegistry, get_registry
+from ..sse import json_event
+
+router = APIRouter(prefix="/jobs", tags=["jobs"])
+
+
+class JobRun(BaseModel):
+    component_id: str
+    config_id: str
+    config_row_ids: list[str] | None = None
+    branch_id: int | None = None
+    variable_values_id: str | None = None
+    no_variables: bool = False
+    mode: str = DEFAULT_JOB_MODE
+
+
+class JobTerminate(BaseModel):
+    job_ids: list[str] | None = None
+    status: str | None = None
+    component_id: str | None = None
+    config_id: str | None = None
+    branch_id: int | None = None
+    limit: int | None = None
+    dry_run: bool = False
+
+
+@router.get("", summary="List jobs across projects")
+def list_jobs(
+    project: list[str] | None = Query(None),
+    component_id: str | None = None,
+    config_id: str | None = None,
+    status: str | None = None,
+    limit: int = 50,
+    registry: ServiceRegistry = Depends(get_registry),
+) -> dict[str, Any]:
+    """List jobs across one or more projects. Mirrors `kbagent job list`."""
+    return registry.job.list_jobs(
+        aliases=project,
+        component_id=component_id,
+        config_id=config_id,
+        status=status,
+        limit=limit,
+    )
+
+
+@router.get("/{project}/{job_id}", summary="Get job detail")
+def detail(
+    project: str, job_id: str, registry: ServiceRegistry = Depends(get_registry)
+) -> dict[str, Any]:
+    """Fetch detail for a single job. Mirrors `kbagent job detail`."""
+    return registry.job.get_job_detail(alias=project, job_id=job_id)
+
+
+@router.post("/{project}/run", summary="Run a component configuration")
+def run(
+    project: str,
+    body: JobRun,
+    wait: bool = False,
+    timeout: float = 300.0,
+    poll_strategy: str = DEFAULT_POLL_STRATEGY,
+    log_tail_lines: int = DEFAULT_LOG_TAIL_LINES,
+    registry: ServiceRegistry = Depends(get_registry),
+) -> dict[str, Any]:
+    """Run a component configuration and optionally wait for completion. Mirrors `kbagent job run`."""
+    return registry.job.run_job(
+        alias=project,
+        component_id=body.component_id,
+        config_id=body.config_id,
+        config_row_ids=body.config_row_ids,
+        wait=wait,
+        timeout=timeout,
+        branch_id=body.branch_id,
+        variable_values_id=body.variable_values_id,
+        no_variables=body.no_variables,
+        poll_strategy=poll_strategy,
+        log_tail_lines=log_tail_lines,
+        mode=body.mode,
+    )
+
+
+@router.post("/{project}/terminate", summary="Terminate running jobs")
+def terminate(
+    project: str, body: JobTerminate, registry: ServiceRegistry = Depends(get_registry)
+) -> dict[str, Any]:
+    """Terminate jobs by id or filter. Mirrors `kbagent job terminate`."""
+    if body.job_ids:
+        return registry.job.terminate_jobs(
+            alias=project, job_ids=body.job_ids, dry_run=body.dry_run
+        )
+    matched = registry.job.resolve_job_ids_by_filter(
+        alias=project,
+        status=body.status,
+        component_id=body.component_id,
+        config_id=body.config_id,
+        branch_id=body.branch_id,
+        limit=body.limit if body.limit is not None else 100,
+    )
+    # resolve_job_ids_by_filter returns full job dicts; extract string IDs
+    job_ids = [str(j.get("id")) for j in matched if j.get("id")]
+    return registry.job.terminate_jobs(alias=project, job_ids=job_ids, dry_run=body.dry_run)
+
+
+@router.get("/{project}/{job_id}/stream", summary="Stream job status and logs (SSE)")
+async def stream_job(
+    project: str,
+    job_id: str,
+    poll_interval: float = 2.0,
+    log_tail_lines: int = 50,
+    registry: ServiceRegistry = Depends(get_registry),
+) -> EventSourceResponse:
+    """SSE stream of job status transitions and recent log events.
+
+    Emits one event per poll while the job is non-terminal; emits a final
+    ``status`` event when the job reaches a terminal state, then ends.
+    """
+    projects = registry.job.resolve_projects([project])
+    proj = projects[project]
+
+    async def gen() -> AsyncIterator[dict[str, str]]:
+        last_status: str | None = None
+        last_event_id: int | None = None
+        while True:
+            try:
+                detail = await asyncio.to_thread(
+                    registry.job.get_job_detail, alias=project, job_id=job_id
+                )
+            except Exception as exc:
+                yield json_event({"error": str(exc)}, event="error")
+                return
+            current_status = str(detail.get("status") or "")
+            if current_status != last_status:
+                yield json_event({"status": current_status, "job": detail}, event="status")
+                last_status = current_status
+
+            run_id = str(detail.get("runId") or detail.get("id") or job_id)
+            try:
+                client = registry.job._client_factory(proj.stack_url, proj.token)
+                try:
+                    events = await asyncio.to_thread(
+                        client.fetch_job_events, run_id, limit=log_tail_lines
+                    )
+                finally:
+                    client.close()
+            except Exception:
+                events = []
+            for ev in events or []:
+                ev_id_raw = ev.get("id")
+                try:
+                    ev_id = int(ev_id_raw) if ev_id_raw is not None else None
+                except (TypeError, ValueError):
+                    ev_id = None
+                if ev_id is None or last_event_id is None or ev_id > last_event_id:
+                    yield json_event(ev, event="log")
+                    if ev_id is not None and (last_event_id is None or ev_id > last_event_id):
+                        last_event_id = ev_id
+
+            if current_status in {"success", "error", "warning", "terminated", "cancelled"}:
+                yield json_event({"final": current_status, "job": detail}, event="done")
+                return
+            await asyncio.sleep(poll_interval)
+
+    return EventSourceResponse(gen())

keboola_agent_cli/server/routers/kai.py

@@ -0,0 +1,80 @@
+"""Kai (Keboola AI) chat endpoints."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, Depends
+from pydantic import BaseModel
+
+from ..dependencies import ServiceRegistry, get_registry
+
+router = APIRouter(prefix="/kai", tags=["kai"])
+
+
+class KaiMessage(BaseModel):
+    message: str
+    chat_id: str | None = None
+    project: str | None = None
+
+
+@router.get("/ping", summary="Kai liveness probe")
+def ping(
+    project: str | None = None, registry: ServiceRegistry = Depends(get_registry)
+) -> dict[str, Any]:
+    """Quick reachability check against the Kai endpoint for `project`."""
+    return registry.kai.ping(registry.kai.resolve_alias(project))
+
+
+@router.get("/preflight", summary="Inspect Kai readiness")
+def preflight(
+    project: str | None = None, registry: ServiceRegistry = Depends(get_registry)
+) -> dict[str, Any]:
+    """Inspect the configured token's Kai readiness without raising.
+
+    Used by the UI to render a single, informative warning ('use the master
+    "owner" token + enable AI Agent Chat') instead of letting /ping or /chat
+    blow up with KAI_NOT_ENABLED on every interaction.
+    """
+    return registry.kai.preflight(registry.kai.resolve_alias(project))
+
+
+@router.post("/ask", summary="Single-shot Kai question")
+def ask(body: KaiMessage, registry: ServiceRegistry = Depends(get_registry)) -> dict[str, Any]:
+    """Stateless one-off question (no chat history). Mirrors `kbagent kai ask`."""
+    return registry.kai.ask(alias=registry.kai.resolve_alias(body.project), message=body.message)
+
+
+@router.post("/chat", summary="Continue a Kai chat")
+def chat(body: KaiMessage, registry: ServiceRegistry = Depends(get_registry)) -> dict[str, Any]:
+    """Send a message in a stateful chat (omit `chat_id` to start a new one).
+    Mirrors `kbagent kai chat`.
+    """
+    return registry.kai.chat_message(
+        alias=registry.kai.resolve_alias(body.project),
+        message=body.message,
+        chat_id=body.chat_id,
+    )
+
+
+@router.get("/history", summary="List recent Kai chats")
+def history(
+    project: str | None = None,
+    limit: int = 10,
+    registry: ServiceRegistry = Depends(get_registry),
+) -> dict[str, Any]:
+    """List the most recent `limit` chats for `project`. Mirrors
+    `kbagent kai history`.
+    """
+    return registry.kai.get_history(alias=registry.kai.resolve_alias(project), limit=limit)
+
+
+@router.get("/chat/{chat_id}", summary="Replay one chat")
+def chat_detail(
+    chat_id: str,
+    project: str | None = None,
+    registry: ServiceRegistry = Depends(get_registry),
+) -> dict[str, Any]:
+    """Fetch the full message history for one chat (used to restore a
+    conversation after the user navigates away and back)."""
+    return registry.kai.get_chat_detail(alias=registry.kai.resolve_alias(project), chat_id=chat_id)