Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

10.5 KB
Raw Blame
"""Models and stable limits for VikingBot compile tasks."""

from __future__ import annotations

from datetime import datetime, timezone
from typing import Any, Literal

from pydantic import BaseModel, ConfigDict, Field, PrivateAttr, model_validator

from openviking.session.memory.dataclass import WikiLink
from vikingbot.channels.openapi_models import OpenVikingConnection

DEFAULT_COMPILE_INSTRUCTION = (
    "Follow the loaded Skill's instructions to transform the provided source materials "
    "into the outputs required by the Skill."
)
COMPILE_STAGING_ROOT = "__compile_staging__"
COMPILE_OUTPUT_ROOT = f"{COMPILE_STAGING_ROOT}/output"
COMPILE_DRAFT_ROOT = f"{COMPILE_STAGING_ROOT}/drafts"
OKF_VERSION = "0.1"
TERMINAL_STATUSES = frozenset({"completed", "failed", "cancelled"})
WikiLanguage = Literal["en", "zh-CN"]


class CompileLimits(BaseModel):
    """Bound task execution and source loading; output size is checked per submission."""

    model_config = ConfigDict(frozen=True)

    # Soft request budget for prompt, input JSON, emit schema and estimated output space.
    # Larger indivisible records may exceed it; this is not the model's token limit.
    merge_input_chars: int = Field(default=60_000, ge=1)
    # Source text plus repeated context per range/read batch, independent of request packing.
    source_batch_chars: int = Field(default=40_000, ge=1)
    agent_iterations: int = 120
    # Per-transform model/tool rounds, including draft checks and submission; parent budget is separate.
    subagent_iterations: int = Field(default=70, ge=1)
    # Final delivery review has a task-wide model/tool-round budget, including submission.
    final_review_iterations: int = Field(default=300, ge=1)
    # Per-task Map workers, also used for Resource source subagents.
    source_concurrency: int = Field(default=6, ge=1)
    # Per-task Shuffle routing workers and embedding batches.
    shuffle_concurrency: int = Field(default=6, ge=1)
    # Maximum primary records per routing request, including retried records.
    shuffle_batch_size: int = Field(default=4, ge=1, strict=True)
    # Per-task Reduce workers, also used for consolidating same-path candidate files.
    merge_concurrency: int = Field(default=10, ge=1)
    concurrent_tasks: int = 10
    accepted_tasks: int = 40
    accepted_tasks_per_principal: int = 10
    salvage_grace_seconds: float = 120
    cleanup_grace_seconds: float = 40
    terminal_task_retention_seconds: float = 24 * 60 * 60
    terminal_task_records: int = 1000


class CompileRequest(BaseModel):
    model_config = ConfigDict(extra="forbid", populate_by_name=True)

    from_: list[str] = Field(alias="from", min_length=1)
    to: str = Field(min_length=1)
    instruction: str | None = None
    skill: str = Field(min_length=1)
    args: dict[str, Any] | None = None
    openviking_connection: OpenVikingConnection | None = None
    _principal_scope: str = PrivateAttr(default="local")

    @model_validator(mode="before")
    @classmethod
    def _accept_reason(cls, data: Any) -> Any:
        if isinstance(data, dict) and "reason" in data:
            data = dict(data)
            data.setdefault("instruction", data.pop("reason"))
        return data


class SanitizedCompileRequest(BaseModel):
    model_config = ConfigDict(extra="forbid", populate_by_name=True)

    from_: list[str] = Field(alias="from")
    to: str
    instruction: str
    instruction_provided: bool = False
    skill: str
    # Inclusive source modification cutoff in UTC; None compiles all source files.
    last_compile_time: datetime | None = None
    # Kernel change plan for incremental Compile; supersedes last_compile_time.
    changes: dict[str, Any] | None = None
    # Rebuild resource index.md files from actual Markdown paths; preserve knowledge bodies.
    wiki_links: bool = Field(default=False, strict=True)


def has_directory_plan(changes: dict[str, Any] | None) -> bool:
    """Identify directory-based task inputs; request normalization validates their contents."""
    return isinstance(changes, dict) and "diff_dirs" in changes and "full_dirs" in changes


class WikiPageDraft(BaseModel):
    model_config = ConfigDict(extra="forbid")

    page_id: int
    title: str
    page_type: str
    summary: str
    body_markdown: str | None = Field(
        default=None,
        description=(
            "Inline Markdown body for an actual Wiki page. Link relevant known source "
            "URIs with ordinary Markdown links; never invent link targets. For very large "
            "bodies, write the Markdown to the workspace with write_file and submit "
            "body_workspace_path instead."
        ),
    )
    body_workspace_path: str | None = Field(
        default=None,
        description=(
            f"Relative path under {COMPILE_OUTPUT_ROOT}/ for an editable "
            "UTF-8 Markdown Wiki page in the output directory."
        ),
    )
    source_ids: list[str] = Field(
        default_factory=list,
        description=(
            "Identifiers of supplied source roots that support this Wiki page. Omit to "
            "cite every supplied source root."
        ),
    )
    tags: list[str] = Field(default_factory=list)
    path_hint: str | None = Field(
        default=None,
        description=(
            "Optional relative path for a new Wiki page. Omit by default so its filename "
            "derives from title; use only for Skill-required paths and avoid generic basenames."
        ),
    )
    update_uri: str | None = None

    @model_validator(mode="after")
    def validate_body(self) -> "WikiPageDraft":
        if (self.body_markdown is None) == (self.body_workspace_path is None):
            raise ValueError("exactly one of body_markdown or body_workspace_path is required")
        return self


class CompileFileDraft(BaseModel):
    model_config = ConfigDict(extra="forbid")

    path: str | None = Field(
        default=None,
        description="Relative target path for a new file under the Compile target.",
    )
    update_uri: str | None = Field(
        default=None,
        description="Catalog URI of an existing target file to replace.",
    )
    content: str | None = Field(
        default=None,
        description=(
            "Exact UTF-8 text file content, including any required frontmatter. For very "
            "large files, write the file to the workspace with write_file and submit "
            "workspace_path instead."
        ),
    )
    workspace_path: str | None = Field(
        default=None,
        description=(
            "Explicit relative path of a file already generated in the task workspace; "
            "its bytes are preserved exactly."
        ),
    )

    @model_validator(mode="after")
    def validate_shape(self) -> "CompileFileDraft":
        if (self.path is None) == (self.update_uri is None):
            raise ValueError("exactly one of path or update_uri is required")
        if (self.content is None) == (self.workspace_path is None):
            raise ValueError("exactly one of content or workspace_path is required")
        return self


class WikiBundleDraft(BaseModel):
    model_config = ConfigDict(extra="forbid")

    pages: list[WikiPageDraft] = Field(
        description=("Actual Wiki pages only; do not place Skill-prescribed artifact files here.")
    )
    files: list[CompileFileDraft] = Field(
        default_factory=list,
        description=(
            "Skill-prescribed exact-path artifacts, including Markdown, YAML, JSON, "
            "and binary files; preserve every required path and format."
        ),
    )
    links: list[WikiLink] = Field(
        default_factory=list,
        description=(
            "Useful non-self relationships between generated Wiki pages only; omit "
            "them when no valid related page exists."
        ),
    )


class CompileErrorInfo(BaseModel):
    model_config = ConfigDict(extra="forbid")

    code: str
    message: str


class CompileResult(BaseModel):
    model_config = ConfigDict(extra="forbid", populate_by_name=True)

    from_: list[str] = Field(alias="from")
    to: str
    skill: str
    okf_version: str = OKF_VERSION
    created: list[str] = Field(default_factory=list)
    updated: list[str] = Field(default_factory=list)
    unchanged: list[str] = Field(default_factory=list)
    # Skipped target-state conflicts, each containing uri, code and message; never delivered.
    conflicts: list[dict[str, str]] = Field(default_factory=list)
    page_count: int = 0
    link_count: int = 0
    # Path diagnostics are informational and never consume the agent repair budget.
    link_report: dict[str, Any] = Field(default_factory=dict)
    warnings: list[str] = Field(default_factory=list)


class CompileTask(BaseModel):
    model_config = ConfigDict(extra="forbid")

    task_id: str
    principal_scope: str
    sanitized_request: SanitizedCompileRequest
    status: Literal[
        "accepted",
        "running",
        "committing",
        "cancelling",
        "completed",
        "failed",
        "cancelled",
    ]
    stage: str
    created_at: str
    updated_at: str
    meta: dict[str, Any] = Field(default_factory=dict)
    result: CompileResult | None = None
    error: CompileErrorInfo | None = None

    def public_dict(self) -> dict[str, Any]:
        data = self.model_dump(exclude={"principal_scope", "sanitized_request"}, exclude_none=True)
        if self.result is not None:
            data["result"] = self.result.model_dump(by_alias=True)
        return data


class CompileAccepted(BaseModel):
    model_config = ConfigDict(extra="forbid")

    session_id: str
    task_id: str
    status: Literal["accepted"] = "accepted"
    to: str


class CompileSessionRequest(BaseModel):
    """Status or cancellation request scoped by the authenticated caller and session ID."""

    model_config = ConfigDict(extra="forbid")

    session_id: str = Field(min_length=1)
    # Original task args forwarded by OpenViking; optional and unused for session lookup.
    args: dict[str, Any] | None = None


class CompileFailure(RuntimeError):
    def __init__(self, code: str, message: str, *, stage: str):
        super().__init__(message)
        self.code = code
        self.stage = stage


def utc_now() -> str:
    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")


__all__ = [
    "CompileAccepted",
    "CompileErrorInfo",
    "CompileFileDraft",
    "CompileFailure",
    "CompileLimits",
    "CompileRequest",
    "CompileResult",
    "CompileSessionRequest",
    "CompileTask",
    "DEFAULT_COMPILE_INSTRUCTION",
    "OKF_VERSION",
    "SanitizedCompileRequest",
    "TERMINAL_STATUSES",
    "WikiBundleDraft",
    "WikiLanguage",
    "WikiPageDraft",
    "utc_now",
]