kairo-code 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

kairo/backend/models/agent.py

@@ -1,7 +1,9 @@
 import uuid
 from datetime import datetime, UTC
+from typing import Any
 
-from sqlalchemy import DateTime, ForeignKey, String, Text
+from sqlalchemy import BigInteger, Boolean, DateTime, Float, ForeignKey, Integer, String, Text, Date
+from sqlalchemy.dialects.postgresql import JSONB
 from sqlalchemy.orm import Mapped, mapped_column
 
 from backend.core.database import Base
@@ -20,11 +22,223 @@ class Agent(Base):
     system_prompt: Mapped[str | None] = mapped_column(Text, nullable=True)
     model_preference: Mapped[str] = mapped_column(String, default="nyx")
     tools_config: Mapped[str | None] = mapped_column(Text, nullable=True)
-    status: Mapped[str] = mapped_column(String, default="offline")
+
+    # State machine: created -> online -> idle/busy -> offline -> stale -> disabled
+    state: Mapped[str] = mapped_column(String, default="created")
+    status: Mapped[str] = mapped_column(String, default="offline")  # Legacy, maps to state
+    agent_type: Mapped[str] = mapped_column(String, default="sdk")  # sdk or container
+
+    # Connection info
+    sdk_version: Mapped[str | None] = mapped_column(String, nullable=True)
+    host_info: Mapped[dict | None] = mapped_column(JSONB, nullable=True)
     last_heartbeat_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    last_online_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    first_connected_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+
+    # Restart tracking
+    restart_count: Mapped[int] = mapped_column(Integer, default=0)
+    last_restart_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    last_restart_reason: Mapped[str | None] = mapped_column(String, nullable=True)
+
+    # Error tracking
+    last_error_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    last_error_message: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    # Soft delete
+    deleted_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+
     created_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), default=lambda: datetime.now(UTC)
     )
     updated_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), default=lambda: datetime.now(UTC), onupdate=lambda: datetime.now(UTC)
     )
+
+
+class AgentMetrics1m(Base):
+    """1-minute granularity metrics (30 day retention)"""
+    __tablename__ = "agent_metrics_1m"
+
+    id: Mapped[str] = mapped_column(primary_key=True, default=lambda: str(uuid.uuid4()))
+    agent_id: Mapped[str] = mapped_column(ForeignKey("agents.id", ondelete="CASCADE"))
+    bucket_time: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+
+    request_count: Mapped[int] = mapped_column(Integer, default=0)
+    error_count: Mapped[int] = mapped_column(Integer, default=0)
+    timeout_count: Mapped[int] = mapped_column(Integer, default=0)
+    input_tokens: Mapped[int] = mapped_column(BigInteger, default=0)
+    output_tokens: Mapped[int] = mapped_column(BigInteger, default=0)
+    total_latency_ms: Mapped[int] = mapped_column(BigInteger, default=0)
+    min_latency_ms: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    max_latency_ms: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    tool_calls: Mapped[int] = mapped_column(Integer, default=0)
+    tool_errors: Mapped[int] = mapped_column(Integer, default=0)
+    tool_breakdown: Mapped[dict | None] = mapped_column(JSONB, nullable=True)
+    model_breakdown: Mapped[dict | None] = mapped_column(JSONB, nullable=True)
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(UTC)
+    )
+
+
+class AgentMetrics1h(Base):
+    """1-hour granularity metrics (1 year retention)"""
+    __tablename__ = "agent_metrics_1h"
+
+    id: Mapped[str] = mapped_column(primary_key=True, default=lambda: str(uuid.uuid4()))
+    agent_id: Mapped[str] = mapped_column(ForeignKey("agents.id", ondelete="CASCADE"))
+    bucket_time: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+
+    request_count: Mapped[int] = mapped_column(Integer, default=0)
+    error_count: Mapped[int] = mapped_column(Integer, default=0)
+    timeout_count: Mapped[int] = mapped_column(Integer, default=0)
+    input_tokens: Mapped[int] = mapped_column(BigInteger, default=0)
+    output_tokens: Mapped[int] = mapped_column(BigInteger, default=0)
+    total_latency_ms: Mapped[int] = mapped_column(BigInteger, default=0)
+    min_latency_ms: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    max_latency_ms: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    p50_latency_ms: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    p99_latency_ms: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    tool_calls: Mapped[int] = mapped_column(Integer, default=0)
+    tool_errors: Mapped[int] = mapped_column(Integer, default=0)
+    tool_breakdown: Mapped[dict | None] = mapped_column(JSONB, nullable=True)
+    model_breakdown: Mapped[dict | None] = mapped_column(JSONB, nullable=True)
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(UTC)
+    )
+
+
+class AgentMetricsDaily(Base):
+    """Daily granularity metrics (2 year retention)"""
+    __tablename__ = "agent_metrics_daily"
+
+    id: Mapped[str] = mapped_column(primary_key=True, default=lambda: str(uuid.uuid4()))
+    agent_id: Mapped[str] = mapped_column(ForeignKey("agents.id", ondelete="CASCADE"))
+    date: Mapped[datetime] = mapped_column(Date)
+
+    request_count: Mapped[int] = mapped_column(Integer, default=0)
+    error_count: Mapped[int] = mapped_column(Integer, default=0)
+    timeout_count: Mapped[int] = mapped_column(Integer, default=0)
+    input_tokens: Mapped[int] = mapped_column(BigInteger, default=0)
+    output_tokens: Mapped[int] = mapped_column(BigInteger, default=0)
+    total_latency_ms: Mapped[int] = mapped_column(BigInteger, default=0)
+    min_latency_ms: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    max_latency_ms: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    avg_latency_ms: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    p50_latency_ms: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    p99_latency_ms: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    tool_calls: Mapped[int] = mapped_column(Integer, default=0)
+    tool_errors: Mapped[int] = mapped_column(Integer, default=0)
+    tool_breakdown: Mapped[dict | None] = mapped_column(JSONB, nullable=True)
+    model_breakdown: Mapped[dict | None] = mapped_column(JSONB, nullable=True)
+    uptime_seconds: Mapped[int] = mapped_column(Integer, default=0)
+    downtime_seconds: Mapped[int] = mapped_column(Integer, default=0)
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(UTC)
+    )
+
+
+class AgentEvent(Base):
+    """Agent events log"""
+    __tablename__ = "agent_events"
+
+    id: Mapped[str] = mapped_column(primary_key=True, default=lambda: str(uuid.uuid4()))
+    agent_id: Mapped[str] = mapped_column(ForeignKey("agents.id", ondelete="CASCADE"))
+    event_type: Mapped[str] = mapped_column(String)  # heartbeat, connection, error, restart, config_change
+    event_data: Mapped[dict | None] = mapped_column(JSONB, nullable=True)
+    error_type: Mapped[str | None] = mapped_column(String, nullable=True)
+    error_message: Mapped[str | None] = mapped_column(Text, nullable=True)
+    session_id: Mapped[str | None] = mapped_column(String, nullable=True)
+    client_ip: Mapped[str | None] = mapped_column(String, nullable=True)
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(UTC)
+    )
+
+
+class AgentAlertConfig(Base):
+    """Alert configuration per agent"""
+    __tablename__ = "agent_alert_configs"
+
+    id: Mapped[str] = mapped_column(primary_key=True, default=lambda: str(uuid.uuid4()))
+    agent_id: Mapped[str] = mapped_column(ForeignKey("agents.id", ondelete="CASCADE"))
+    user_id: Mapped[str] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"))
+    name: Mapped[str] = mapped_column(String)
+    alert_type: Mapped[str] = mapped_column(String)  # offline, error_rate, latency, token_budget
+    metric: Mapped[str] = mapped_column(String)
+    condition: Mapped[str] = mapped_column(String)  # gt, lt, gte, lte, eq
+    threshold: Mapped[float] = mapped_column(Float)
+    window_seconds: Mapped[int] = mapped_column(Integer, default=300)
+    cooldown_seconds: Mapped[int] = mapped_column(Integer, default=3600)
+    severity: Mapped[str] = mapped_column(String, default="warning")
+    channels: Mapped[list] = mapped_column(JSONB, default=lambda: ["email"])
+    is_enabled: Mapped[bool] = mapped_column(Boolean, default=True)
+    last_triggered_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(UTC)
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(UTC), onupdate=lambda: datetime.now(UTC)
+    )
+
+
+class AgentAlertHistory(Base):
+    """Alert history/incidents"""
+    __tablename__ = "agent_alert_history"
+
+    id: Mapped[str] = mapped_column(primary_key=True, default=lambda: str(uuid.uuid4()))
+    config_id: Mapped[str] = mapped_column(ForeignKey("agent_alert_configs.id", ondelete="CASCADE"))
+    agent_id: Mapped[str] = mapped_column(ForeignKey("agents.id", ondelete="CASCADE"))
+    alert_type: Mapped[str] = mapped_column(String)
+    severity: Mapped[str] = mapped_column(String)
+    status: Mapped[str] = mapped_column(String, default="triggered")  # triggered, acknowledged, resolved
+    message: Mapped[str | None] = mapped_column(Text, nullable=True)
+    trigger_value: Mapped[float | None] = mapped_column(Float, nullable=True)
+    threshold_value: Mapped[float | None] = mapped_column(Float, nullable=True)
+    acknowledged_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    acknowledged_by: Mapped[str | None] = mapped_column(ForeignKey("users.id", ondelete="SET NULL"), nullable=True)
+    resolved_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(UTC)
+    )
+
+
+class AgentSetupToken(Base):
+    """One-time setup tokens for guided deployment wizard"""
+    __tablename__ = "agent_setup_tokens"
+
+    id: Mapped[str] = mapped_column(primary_key=True, default=lambda: str(uuid.uuid4()))
+    agent_id: Mapped[str] = mapped_column(ForeignKey("agents.id", ondelete="CASCADE"))
+    user_id: Mapped[str] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"))
+    token_hash: Mapped[str] = mapped_column(String, unique=True)
+    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    used: Mapped[bool] = mapped_column(Boolean, default=False)
+    used_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    used_from_ip: Mapped[str | None] = mapped_column(String, nullable=True)
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(UTC)
+    )
+
+
+class AgentCommand(Base):
+    """Pending commands for agents (delivered via heartbeat)"""
+    __tablename__ = "agent_commands"
+
+    id: Mapped[str] = mapped_column(primary_key=True, default=lambda: str(uuid.uuid4()))
+    agent_id: Mapped[str] = mapped_column(ForeignKey("agents.id", ondelete="CASCADE"))
+    command_type: Mapped[str] = mapped_column(String)  # restart, stop, config_refresh
+    payload: Mapped[dict | None] = mapped_column(JSONB, nullable=True)
+    issued_by: Mapped[str | None] = mapped_column(ForeignKey("users.id", ondelete="SET NULL"), nullable=True)
+    status: Mapped[str] = mapped_column(String, default="pending")  # pending, dispatched, acknowledged, expired
+    dispatched_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    acknowledged_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(UTC)
+    )

kairo/backend/models/api_key.py

@@ -12,6 +12,9 @@ class ApiKey(Base):
 
     id: Mapped[str] = mapped_column(primary_key=True, default=lambda: str(uuid.uuid4()))
     user_id: Mapped[str] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"), index=True)
+    agent_id: Mapped[str | None] = mapped_column(
+        ForeignKey("agents.id", ondelete="CASCADE"), nullable=True, index=True
+    )
     name: Mapped[str] = mapped_column(String)
     key_prefix: Mapped[str] = mapped_column(String, index=True)
     key_hash: Mapped[str] = mapped_column(String)
@@ -21,5 +24,5 @@ class ApiKey(Base):
         DateTime(timezone=True), default=lambda: datetime.now(UTC)
     )
     expires_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
-    key_type: Mapped[str] = mapped_column(String, default="api")
+    key_type: Mapped[str] = mapped_column(String, default="api")  # api, agent
     rate_limit_rpm: Mapped[int] = mapped_column(Integer, default=60)

kairo/backend/models/task.py

@@ -0,0 +1,31 @@
+import uuid
+from datetime import datetime, UTC
+
+from sqlalchemy import DateTime, ForeignKey, JSON, String, Text
+from sqlalchemy.orm import Mapped, mapped_column
+
+from backend.core.database import Base
+
+
+class Task(Base):
+    __tablename__ = "tasks"
+
+    id: Mapped[str] = mapped_column(primary_key=True, default=lambda: str(uuid.uuid4()))
+    agent_id: Mapped[str | None] = mapped_column(
+        ForeignKey("agents.id", ondelete="SET NULL"), nullable=True
+    )
+    user_id: Mapped[str] = mapped_column(
+        ForeignKey("users.id", ondelete="CASCADE"), nullable=False
+    )
+    status: Mapped[str] = mapped_column(String, default="pending")
+    input: Mapped[dict] = mapped_column(JSON, nullable=False)
+    output: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+    error: Mapped[str | None] = mapped_column(Text, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(UTC)
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(UTC), onupdate=lambda: datetime.now(UTC)
+    )
+    claimed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)

kairo/backend/models/user_provider_key.py

@@ -0,0 +1,26 @@
+import uuid
+from datetime import datetime, UTC
+
+from sqlalchemy import DateTime, ForeignKey, String, Text
+from sqlalchemy.orm import Mapped, mapped_column
+
+from backend.core.database import Base
+
+
+class UserProviderKey(Base):
+    __tablename__ = "user_provider_keys"
+
+    id: Mapped[str] = mapped_column(primary_key=True, default=lambda: str(uuid.uuid4()))
+    user_id: Mapped[str] = mapped_column(
+        ForeignKey("users.id", ondelete="CASCADE"), index=True, nullable=False
+    )
+    provider: Mapped[str] = mapped_column(String(50), nullable=False)  # "openai", "anthropic"
+    encrypted_key: Mapped[str] = mapped_column(Text, nullable=False)   # Fernet-encrypted
+    key_suffix: Mapped[str] = mapped_column(String(8), nullable=False) # last 4 chars for display
+    label: Mapped[str | None] = mapped_column(String(100), nullable=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(UTC)
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(UTC), onupdate=lambda: datetime.now(UTC)
+    )

kairo/backend/schemas/agent.py

@@ -1,13 +1,17 @@
 from datetime import datetime
+from typing import Any
 
 from pydantic import BaseModel, Field
 
 
+# ─── Agent CRUD ───────────────────────────────────────────────────────────────
+
 class RegisterAgentRequest(BaseModel):
     name: str = Field(..., min_length=1, max_length=100)
     description: str | None = Field(None, max_length=500)
     system_prompt: str | None = Field(None, max_length=10000)
     model_preference: str = "nyx"
+    agent_type: str = Field("sdk", pattern="^(sdk|container)$")
     tools: list[str] | None = None
 
 
@@ -24,19 +28,262 @@ class AgentResponse(BaseModel):
     name: str
     description: str | None = None
     model_preference: str
-    status: str
+    agent_type: str
+    state: str
+    status: str  # Legacy
+    sdk_version: str | None = None
+    host_info: dict | None = None
     last_heartbeat_at: datetime | None = None
+    last_online_at: datetime | None = None
+    first_connected_at: datetime | None = None
+    restart_count: int = 0
+    last_error_at: datetime | None = None
+    last_error_message: str | None = None
     created_at: datetime
     updated_at: datetime
 
     model_config = {"from_attributes": True}
 
 
+class AgentListResponse(BaseModel):
+    """Agent list item with summary metrics"""
+    id: str
+    name: str
+    description: str | None = None
+    model_preference: str
+    agent_type: str
+    state: str
+    sdk_version: str | None = None
+    last_heartbeat_at: datetime | None = None
+    created_at: datetime
+    # Summary metrics (last 24h)
+    requests_24h: int = 0
+    errors_24h: int = 0
+    tokens_24h: int = 0
+    error_rate: float = 0.0
+
+    model_config = {"from_attributes": True}
+
+
+# ─── Heartbeat ────────────────────────────────────────────────────────────────
+
+class HostInfo(BaseModel):
+    hostname: str | None = None
+    ip: str | None = None
+    os: str | None = None
+    memory_mb: int | None = None
+    memory_used_percent: float | None = None
+
+
+class ProcessInfo(BaseModel):
+    pid: int | None = None
+    uptime_seconds: int | None = None
+    memory_rss_mb: int | None = None
+    cpu_percent: float | None = None
+    thread_count: int | None = None
+
+
+class MetricsSinceLastHeartbeat(BaseModel):
+    requests_completed: int = 0
+    requests_failed: int = 0
+    total_latency_ms: int = 0
+    input_tokens: int = 0
+    output_tokens: int = 0
+    tool_calls: int = 0
+    tool_errors: int = 0
+
+
 class AgentHeartbeatRequest(BaseModel):
     agent_id: str
-    status: str = Field("online", pattern="^(online|busy|idle)$")
+    status: str = Field("online", pattern="^(online|busy|idle|error)$")
+    sdk_version: str | None = None
+    host_info: HostInfo | None = None
+    process_info: ProcessInfo | None = None
+    metrics_since_last_heartbeat: MetricsSinceLastHeartbeat | None = None
+    queue_depth: int | None = None
+    active_request: bool = False
+    last_error: dict | None = None
+
+
+class AgentCommand(BaseModel):
+    command_id: str
+    type: str
+    payload: dict | None = None
+    issued_at: datetime
+    expires_at: datetime
+    signature: str
 
 
 class AgentHeartbeatResponse(BaseModel):
     acknowledged: bool
     server_time: datetime
+    commands: list[AgentCommand] = []
+
+
+# ─── Metrics ──────────────────────────────────────────────────────────────────
+
+class AgentMetricsQuery(BaseModel):
+    range: str = Field("24h", pattern="^(1h|6h|24h|7d|30d)$")
+    granularity: str = Field("auto", pattern="^(auto|1m|1h|1d)$")
+
+
+class MetricDataPoint(BaseModel):
+    timestamp: datetime
+    request_count: int = 0
+    error_count: int = 0
+    input_tokens: int = 0
+    output_tokens: int = 0
+    avg_latency_ms: float | None = None
+    p99_latency_ms: int | None = None
+    tool_calls: int = 0
+
+
+class AgentMetricsResponse(BaseModel):
+    agent_id: str
+    range: str
+    granularity: str
+    data: list[MetricDataPoint]
+    summary: dict
+
+
+# ─── Events ───────────────────────────────────────────────────────────────────
+
+class AgentEventResponse(BaseModel):
+    id: str
+    event_type: str
+    event_data: dict | None = None
+    error_type: str | None = None
+    error_message: str | None = None
+    client_ip: str | None = None
+    created_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+class AgentEventsQuery(BaseModel):
+    event_type: str | None = None
+    limit: int = Field(50, ge=1, le=500)
+    cursor: str | None = None
+
+
+# ─── Commands ─────────────────────────────────────────────────────────────────
+
+class IssueCommandRequest(BaseModel):
+    command_type: str = Field(..., pattern="^(restart|stop|config_refresh)$")
+    payload: dict | None = None
+
+
+class CommandResponse(BaseModel):
+    id: str
+    command_type: str
+    status: str
+    created_at: datetime
+    expires_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+# ─── Alerts ───────────────────────────────────────────────────────────────────
+
+class CreateAlertConfigRequest(BaseModel):
+    name: str = Field(..., min_length=1, max_length=100)
+    alert_type: str = Field(..., pattern="^(offline|error_rate|latency|token_budget)$")
+    metric: str
+    condition: str = Field(..., pattern="^(gt|lt|gte|lte|eq)$")
+    threshold: float
+    window_seconds: int = Field(300, ge=60, le=86400)
+    cooldown_seconds: int = Field(3600, ge=60, le=604800)
+    severity: str = Field("warning", pattern="^(info|warning|critical)$")
+    channels: list[str] = ["email"]
+
+
+class UpdateAlertConfigRequest(BaseModel):
+    name: str | None = None
+    threshold: float | None = None
+    window_seconds: int | None = None
+    cooldown_seconds: int | None = None
+    severity: str | None = None
+    channels: list[str] | None = None
+    is_enabled: bool | None = None
+
+
+class AlertConfigResponse(BaseModel):
+    id: str
+    name: str
+    alert_type: str
+    metric: str
+    condition: str
+    threshold: float
+    window_seconds: int
+    cooldown_seconds: int
+    severity: str
+    channels: list[str]
+    is_enabled: bool
+    last_triggered_at: datetime | None = None
+    created_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+class AlertHistoryResponse(BaseModel):
+    id: str
+    alert_type: str
+    severity: str
+    status: str
+    message: str | None = None
+    trigger_value: float | None = None
+    threshold_value: float | None = None
+    acknowledged_at: datetime | None = None
+    resolved_at: datetime | None = None
+    created_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+# ─── Setup Token ──────────────────────────────────────────────────────────────
+
+class SetupTokenResponse(BaseModel):
+    token: str  # Only shown once!
+    expires_at: datetime
+    agent_id: str
+
+
+class AgentRegistrationRequest(BaseModel):
+    setup_token: str
+    sdk_version: str
+    host_info: HostInfo | None = None
+
+
+class AgentRegistrationResponse(BaseModel):
+    agent_id: str
+    name: str
+    model_preference: str
+    system_prompt: str | None = None
+    api_key: str  # Agent-scoped API key, shown once
+
+
+# ─── Telemetry Batch ──────────────────────────────────────────────────────────
+
+class TelemetryEvent(BaseModel):
+    request_id: str
+    timestamp_start: datetime
+    timestamp_end: datetime
+    latency_ms: int
+    input_tokens: int
+    output_tokens: int
+    model: str
+    status: str = Field(..., pattern="^(success|error|timeout)$")
+    error_type: str | None = None
+    tool_calls: list[dict] | None = None
+
+
+class TelemetryBatchRequest(BaseModel):
+    agent_id: str
+    events: list[TelemetryEvent]
+    idempotency_key: str | None = None
+
+
+class TelemetryBatchResponse(BaseModel):
+    accepted: int
+    rejected: int
+    errors: list[str] = []

kairo/backend/schemas/api_key.py

@@ -16,6 +16,9 @@ class ApiKeyResponse(BaseModel):
     last_used_at: datetime | None = None
     created_at: datetime
     expires_at: datetime | None = None
+    key_type: str = "api"  # api, agent
+    agent_id: str | None = None
+    agent_name: str | None = None
 
     model_config = {"from_attributes": True}
 

kairo/backend/services/agent/__init__.py

@@ -0,0 +1,52 @@
+"""
+Agent services module.
+
+This module provides modular, focused services for agent management:
+
+Core Services:
+- AgentService: Main composite service (backward compatible API)
+- AgentCrudService: CRUD operations for agents
+- AgentHeartbeatService: Heartbeat processing and state management
+- AgentCommandsService: Command issuing and acknowledgment
+- AgentSetupService: Setup tokens and API key creation
+- AgentEventsService: Event logging and queries
+
+Metrics Services:
+- AgentMetricsService: Metrics queries and telemetry processing
+- AgentMetricsRollupService: Background rollup and cleanup jobs
+
+Alerts Services:
+- AgentAlertsService: Alert configuration CRUD
+- AgentAlertsEvaluationService: Background alert evaluation
+
+The main AgentService class composes all sub-services and maintains
+backward compatibility with the original monolithic API.
+"""
+
+from backend.services.agent.agent_service import AgentService
+from backend.services.agent.agent_crud_service import AgentCrudService
+from backend.services.agent.agent_heartbeat_service import AgentHeartbeatService
+from backend.services.agent.agent_commands_service import AgentCommandsService
+from backend.services.agent.agent_metrics_service import AgentMetricsService
+from backend.services.agent.agent_metrics_rollup_service import AgentMetricsRollupService
+from backend.services.agent.agent_alerts_service import AgentAlertsService
+from backend.services.agent.agent_alerts_evaluation_service import AgentAlertsEvaluationService
+from backend.services.agent.agent_setup_service import AgentSetupService
+from backend.services.agent.agent_events_service import AgentEventsService
+
+__all__ = [
+    # Main composite service
+    "AgentService",
+    # Core services
+    "AgentCrudService",
+    "AgentHeartbeatService",
+    "AgentCommandsService",
+    "AgentSetupService",
+    "AgentEventsService",
+    # Metrics services
+    "AgentMetricsService",
+    "AgentMetricsRollupService",
+    # Alerts services
+    "AgentAlertsService",
+    "AgentAlertsEvaluationService",
+]