cairnkit 0.5.0__py3-none-any.whl

cairnkit/__init__.py

@@ -0,0 +1,143 @@
+"""cairnkit: a small agent runtime for business applications.
+
+Design and several algorithms are ported from Hermes Agent v0.23.0 (MIT, Nous Research);
+see NOTICE.md. Public API:
+"""
+
+from cairnkit.agents import AgentConfigError, AgentSpec, load_agent, load_agents, validate_persona
+from cairnkit.compression import (
+    LATEST_MESSAGE_MARKER,
+    SUMMARY_PREFIX,
+    CompressionConfig,
+    CompressionResult,
+    CompressionState,
+    ContextCompressor,
+    estimate_tokens,
+)
+from cairnkit.curator import (
+    CuratorPolicy,
+    CuratorReport,
+    SkillActivity,
+    Suggestion,
+    Transition,
+    plan_transitions,
+    should_run,
+    suggest_consolidation,
+)
+from cairnkit.delegate import make_delegate_tool
+from cairnkit.guardrails import GuardrailConfig
+from cairnkit.llm import (
+    ChatModel,
+    ClassifiedError,
+    FailoverReason,
+    FallbackModel,
+    ModelAPIError,
+    OpenAICompatModel,
+    ScriptedModel,
+    classify_error,
+    openrouter,
+)
+from cairnkit.loop import Agent, RunEvent, RunResult, ToolRecord
+from cairnkit.memory import (
+    MemoryItem,
+    MemoryStore,
+    make_memory_tool,
+    render_snapshot,
+    screen_memory_write,
+)
+from cairnkit.memory_ops import MemoryChange, MemoryPlan, MemoryPlanError, plan_operations
+from cairnkit.pricing import Price, cost_of, estimate_cost
+from cairnkit.prompt import PromptParts, build_system_prompt
+from cairnkit.review import REVIEW_INSTRUCTION, review_conversation
+from cairnkit.search import SearchBackend, SearchHit, SearchItem, make_search_tool
+from cairnkit.security import first_threat_message, scan_for_threats
+from cairnkit.skills import Skill, SkillError, SkillLibrary, make_skill
+from cairnkit.titles import can_replace, derive_title, generate_title
+from cairnkit.tools import (
+    ToolContext,
+    ToolError,
+    ToolOutcome,
+    ToolRegistry,
+    ToolSpec,
+    tool_error,
+    tool_result,
+)
+from cairnkit.types import Message, ModelResponse, ToolCall, Usage
+
+__all__ = [
+    "Agent",
+    "AgentConfigError",
+    "AgentSpec",
+    "build_system_prompt",
+    "can_replace",
+    "ChatModel",
+    "ClassifiedError",
+    "classify_error",
+    "CompressionConfig",
+    "CompressionResult",
+    "CompressionState",
+    "ContextCompressor",
+    "CuratorPolicy",
+    "CuratorReport",
+    "SkillActivity",
+    "Suggestion",
+    "Transition",
+    "plan_transitions",
+    "should_run",
+    "suggest_consolidation",
+    "make_skill",
+    "validate_persona",
+    "LATEST_MESSAGE_MARKER",
+    "cost_of",
+    "derive_title",
+    "estimate_cost",
+    "estimate_tokens",
+    "FailoverReason",
+    "FallbackModel",
+    "first_threat_message",
+    "generate_title",
+    "GuardrailConfig",
+    "load_agent",
+    "load_agents",
+    "make_delegate_tool",
+    "make_memory_tool",
+    "make_search_tool",
+    "MemoryChange",
+    "MemoryItem",
+    "MemoryPlan",
+    "MemoryPlanError",
+    "MemoryStore",
+    "Message",
+    "ModelAPIError",
+    "ModelResponse",
+    "OpenAICompatModel",
+    "openrouter",
+    "plan_operations",
+    "Price",
+    "PromptParts",
+    "render_snapshot",
+    "review_conversation",
+    "REVIEW_INSTRUCTION",
+    "RunEvent",
+    "RunResult",
+    "scan_for_threats",
+    "screen_memory_write",
+    "ScriptedModel",
+    "SearchBackend",
+    "SearchHit",
+    "SearchItem",
+    "Skill",
+    "SkillError",
+    "SkillLibrary",
+    "SUMMARY_PREFIX",
+    "tool_error",
+    "tool_result",
+    "ToolCall",
+    "ToolContext",
+    "ToolError",
+    "ToolOutcome",
+    "ToolRecord",
+    "ToolRegistry",
+    "ToolSpec",
+    "Usage",
+]

cairnkit/agents.py

@@ -0,0 +1,111 @@
+"""Agent definitions loaded from a directory.
+
+    agents/
+      note_structurer/
+        agent.toml    # name, description, tools, skills, limits
+        SOUL.md       # persona and rules (stable prompt tier)
+
+Loading a directory is all a project needs to declare its agents; code only
+supplies the tools and the model.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from cairnkit.guardrails import GuardrailConfig
+from cairnkit.security import first_threat_message
+
+
+class AgentConfigError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class AgentSpec:
+    name: str
+    description: str
+    persona: str
+    model: str = "default"  # key the host maps to a ChatModel
+    tools: list[str] = field(default_factory=list)
+    skills: list[str] = field(default_factory=list)
+    max_iterations: int = 6
+    temperature: float | None = None
+    max_tokens: int | None = None
+    guardrails: GuardrailConfig = field(default_factory=GuardrailConfig)
+
+
+_ALLOWED_KEYS = {
+    "name",
+    "description",
+    "model",
+    "tools",
+    "skills",
+    "max_iterations",
+    "temperature",
+    "max_tokens",
+    "guardrails",
+}
+
+
+MAX_PERSONA_CHARS = 12_000
+
+
+def validate_persona(persona: str) -> str:
+    """Rules for a persona edited outside the repository (for example in an admin page)."""
+    persona = persona.strip()
+    if not persona:
+        raise AgentConfigError("the persona is empty")
+    if len(persona) > MAX_PERSONA_CHARS:
+        raise AgentConfigError(f"the persona may hold at most {MAX_PERSONA_CHARS} characters")
+    if threat := first_threat_message(persona, scope="all"):
+        raise AgentConfigError(threat)
+    return persona
+
+
+def load_agent(directory: str | Path) -> AgentSpec:
+    directory = Path(directory)
+    config_path = directory / "agent.toml"
+    try:
+        data = tomllib.loads(config_path.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        raise AgentConfigError(f"{config_path}: {exc}") from exc
+    unknown = set(data) - _ALLOWED_KEYS
+    if unknown:
+        raise AgentConfigError(f"{config_path}: unknown keys {sorted(unknown)}")
+    name = data.get("name", directory.name)
+    if name != directory.name:
+        raise AgentConfigError(f"{config_path}: name {name!r} must match its directory")
+    soul = directory / "SOUL.md"
+    persona = soul.read_text(encoding="utf-8").strip() if soul.is_file() else ""
+    if not persona:
+        raise AgentConfigError(f"{directory}: SOUL.md is missing or empty")
+    if threat := first_threat_message(persona, scope="all"):
+        raise AgentConfigError(f"{soul}: {threat}")
+    max_iterations = int(data.get("max_iterations", 6))
+    if not 1 <= max_iterations <= 50:
+        raise AgentConfigError(f"{config_path}: max_iterations must be 1-50")
+    return AgentSpec(
+        name=name,
+        description=str(data.get("description", "")),
+        persona=persona,
+        model=str(data.get("model", "default")),
+        tools=list(data.get("tools", [])),
+        skills=list(data.get("skills", [])),
+        max_iterations=max_iterations,
+        temperature=data.get("temperature"),
+        max_tokens=data.get("max_tokens"),
+        guardrails=GuardrailConfig(**data.get("guardrails", {})),
+    )
+
+
+def load_agents(root: str | Path) -> dict[str, AgentSpec]:
+    root = Path(root)
+    if not root.is_dir():
+        raise AgentConfigError(f"agents directory not found: {root}")
+    return {
+        spec.name: spec
+        for spec in (load_agent(d) for d in sorted(root.iterdir()) if (d / "agent.toml").is_file())
+    }