konen 0.1.0__py3-none-any.whl

konen/__init__.py

@@ -0,0 +1,47 @@
+"""Konen public API."""
+
+from .backend import (
+    AIAgent,
+    AITeam,
+    ClaudeEngine,
+    EngineFactory,
+    EngineRouter,
+    GeminiEngine,
+    GPTEngine,
+    InteractionRound,
+    InteractionState,
+    KimiEngine,
+    LLMEngine,
+    LLMPool,
+    LLMResponse,
+    Orchestrator,
+    ProviderHistory,
+    ProviderRound,
+    TranscriptHistory,
+    TranscriptRound,
+    Workspace,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AIAgent",
+    "AITeam",
+    "ClaudeEngine",
+    "EngineFactory",
+    "EngineRouter",
+    "GeminiEngine",
+    "GPTEngine",
+    "InteractionRound",
+    "InteractionState",
+    "KimiEngine",
+    "LLMEngine",
+    "LLMPool",
+    "LLMResponse",
+    "Orchestrator",
+    "ProviderHistory",
+    "ProviderRound",
+    "TranscriptHistory",
+    "TranscriptRound",
+    "Workspace",
+]

konen/backend/__init__.py

@@ -0,0 +1,43 @@
+"""Konen backend API."""
+
+from .ai_agent import AIAgent
+from .ai_team import AITeam
+from .claude_engine import ClaudeEngine
+from .engine_factory import EngineFactory
+from .engine_router import EngineRouter
+from .gemini_engine import GeminiEngine
+from .gpt_engine import GPTEngine
+from .interaction_round import InteractionRound
+from .interaction_state import InteractionState
+from .kimi_engine import KimiEngine
+from .llm_engine import LLMEngine
+from .llm_pool import LLMPool
+from .llm_response import LLMResponse
+from .orchestrator import Orchestrator
+from .provider_history import ProviderHistory
+from .provider_round import ProviderRound
+from .transcript_history import TranscriptHistory
+from .transcript_round import TranscriptRound
+from .workspace import Workspace
+
+__all__ = [
+    "AIAgent",
+    "AITeam",
+    "ClaudeEngine",
+    "EngineFactory",
+    "EngineRouter",
+    "GeminiEngine",
+    "GPTEngine",
+    "InteractionRound",
+    "InteractionState",
+    "KimiEngine",
+    "LLMEngine",
+    "LLMPool",
+    "LLMResponse",
+    "Orchestrator",
+    "ProviderHistory",
+    "ProviderRound",
+    "TranscriptHistory",
+    "TranscriptRound",
+    "Workspace",
+]

konen/backend/ai_agent.py

@@ -0,0 +1,11 @@
+from dataclasses import dataclass, field
+from uuid import uuid4
+
+
+@dataclass(frozen=True, slots=True)
+class AIAgent:
+    """AI agent with a name, description, and identifier."""
+
+    name: str
+    description: str
+    uid: str = field(default_factory=lambda: str(uuid4()))

konen/backend/ai_team.py

@@ -0,0 +1,70 @@
+from collections.abc import Iterable
+
+from .ai_agent import AIAgent
+from .workspace import Workspace
+
+
+class AITeam:
+    """Collection of AI agents indexed by identifier."""
+
+    def __init__(self, agents: Iterable[AIAgent] = ()) -> None:
+        self._agents: dict[str, AIAgent] = {}
+        for agent in agents:
+            self._require_agent_absent(agent.uid)
+            self._agents[agent.uid] = agent
+
+    @classmethod
+    def from_workspace(cls, workspace: Workspace) -> "AITeam":
+        """Build a team from workspace configuration."""
+        agents_data = workspace.load_agents_config()
+        agents_config = agents_data["agents"]
+
+        agents: list[AIAgent] = []
+        for agent_uid, config in agents_config.items():
+            agents.append(
+                AIAgent(
+                    name=config["name"],
+                    description=config["description"],
+                    uid=agent_uid,
+                )
+            )
+        return cls(agents)
+
+    def get_agent(self, agent_uid: str) -> AIAgent:
+        """Return the agent with the given identifier."""
+        self._require_agent_present(agent_uid)
+        return self._agents[agent_uid]
+
+    def list_agents(self) -> list[str]:
+        """Return sorted agent identifiers."""
+        return sorted(self._agents.keys())
+
+    def to_context(self) -> dict[str, dict[str, str]]:
+        """Return agent data as team context."""
+        return {
+            agent_uid: {"name": agent.name, "description": agent.description}
+            for agent_uid, agent in sorted(self._agents.items())
+        }
+
+    def add_agent(self, agent: AIAgent) -> None:
+        """Add an agent."""
+        self._require_agent_absent(agent.uid)
+        self._agents[agent.uid] = agent
+
+    def remove_agent(self, agent_uid: str) -> None:
+        """Remove the agent with the given identifier."""
+        self._require_agent_present(agent_uid)
+        del self._agents[agent_uid]
+
+    def reload_from_workspace(self, workspace: Workspace) -> None:
+        """Reload the team from workspace configuration."""
+        team = self.from_workspace(workspace)
+        self._agents = dict(team._agents)
+
+    def _require_agent_absent(self, agent_uid: str) -> None:
+        if agent_uid in self._agents:
+            raise ValueError(f"Agent '{agent_uid}' already exists in AI team.")
+
+    def _require_agent_present(self, agent_uid: str) -> None:
+        if agent_uid not in self._agents:
+            raise ValueError(f"Agent '{agent_uid}' does not exist in AI team.")

konen/backend/claude_engine.py

@@ -0,0 +1,200 @@
+import copy
+from dataclasses import dataclass
+from typing import Any
+
+from anthropic import Anthropic
+
+from .llm_engine import LLMEngine
+from .llm_response import LLMResponse
+
+
+@dataclass(slots=True)
+class ClaudeEngine(LLMEngine):
+    """Anthropic Claude execution engine."""
+
+    def __post_init__(self) -> None:
+        if self.model_family != "claude":
+            raise ValueError("ClaudeEngine requires model_family='claude'.")
+        super().__post_init__()
+
+    def _initialize_client(self) -> Anthropic:
+        api_key = self.config.get("api_key")
+        if api_key is None:
+            return Anthropic()
+        return Anthropic(api_key=api_key)
+
+    def prepare_provider_state(
+        self, states: list[dict[str, Any]]
+    ) -> dict[str, Any] | None:
+        """Prepare Anthropic message history from prior provider states."""
+        if not states:
+            return None
+
+        messages: list[dict[str, Any]] = []
+        for state in states:
+            user_message = state.get("user_message")
+            assistant_message = state.get("assistant_message")
+
+            if not isinstance(user_message, dict):
+                raise ValueError(
+                    "Claude provider state must contain a 'user_message' dictionary."
+                )
+            if not isinstance(assistant_message, dict):
+                raise ValueError(
+                    "Claude provider state must contain an "
+                    "'assistant_message' dictionary."
+                )
+
+            messages.append(copy.deepcopy(user_message))
+            messages.append(copy.deepcopy(assistant_message))
+
+        return {"messages": messages}
+
+    def generate_response(
+        self,
+        prompt: str,
+        system_instruction: str | None = None,
+        provider_state: dict[str, Any] | None = None,
+    ) -> LLMResponse:
+        """Generate a response with the Anthropic Messages API."""
+        messages = self._previous_messages(provider_state)
+        user_message = {"role": "user", "content": prompt}
+        messages.append(copy.deepcopy(user_message))
+
+        message_kwargs: dict[str, Any] = {
+            "model": self.model_name,
+            "max_tokens": self._max_tokens(),
+            "messages": messages,
+        }
+
+        if system_instruction is not None:
+            message_kwargs["system"] = system_instruction
+
+        thinking = self.config.get("thinking")
+        if thinking is not None:
+            if not isinstance(thinking, dict):
+                raise ValueError(
+                    "ClaudeEngine.config['thinking'] must be a dictionary."
+                )
+            message_kwargs["thinking"] = copy.deepcopy(thinking)
+
+        message = self.client.messages.create(**message_kwargs)
+
+        stop_reason = message.stop_reason
+        if stop_reason is None:
+            raise RuntimeError("Claude message did not return a stop reason.")
+
+        metadata = self._build_response_metadata()
+        metadata["provider_response_id"] = message.id
+        metadata["stop_reason"] = stop_reason
+
+        if message.stop_sequence is not None:
+            metadata["stop_sequence"] = message.stop_sequence
+
+        usage = message.usage
+        cache_creation_tokens = usage.cache_creation_input_tokens or 0
+        cached_tokens = usage.cache_read_input_tokens or 0
+        input_tokens = usage.input_tokens + cache_creation_tokens + cached_tokens
+
+        token_usage: dict[str, int] = {
+            "input_token_count": input_tokens,
+            "output_token_count": usage.output_tokens,
+            "total_token_count": input_tokens + usage.output_tokens,
+        }
+
+        if usage.cache_creation_input_tokens is not None:
+            token_usage["cache_creation_token_count"] = (
+                usage.cache_creation_input_tokens
+            )
+
+        if usage.cache_read_input_tokens is not None:
+            token_usage["cached_token_count"] = usage.cache_read_input_tokens
+
+        output_details = getattr(usage, "output_tokens_details", None)
+        if output_details is not None:
+            thinking_tokens = getattr(output_details, "thinking_tokens", None)
+            if thinking_tokens is not None:
+                token_usage["thinking_token_count"] = thinking_tokens
+
+        metadata["token_usage"] = token_usage
+
+        if stop_reason in {"tool_use", "pause_turn"}:
+            raise RuntimeError(
+                "Claude message requires continuation handling that Konen "
+                f"does not yet implement; stop_reason is '{stop_reason}'."
+            )
+
+        supported_stop_reasons = {
+            "end_turn",
+            "max_tokens",
+            "stop_sequence",
+            "refusal",
+            "model_context_window_exceeded",
+        }
+        if stop_reason not in supported_stop_reasons:
+            raise RuntimeError(f"Unexpected Claude stop reason '{stop_reason}'.")
+
+        text_parts = [block.text for block in message.content if block.type == "text"]
+        text = "".join(text_parts) or None
+
+        assistant_content = [
+            block.model_dump(mode="json", exclude_none=True)
+            for block in message.content
+        ]
+        assistant_message = {"role": "assistant", "content": assistant_content}
+
+        return LLMResponse(
+            text=text,
+            metadata=metadata,
+            provider_state={
+                "user_message": user_message,
+                "assistant_message": assistant_message,
+            },
+        )
+
+    def _max_tokens(self) -> int:
+        """Return the validated maximum output token count."""
+        max_tokens = self.config.get("max_tokens")
+
+        if (
+            not isinstance(max_tokens, int)
+            or isinstance(max_tokens, bool)
+            or max_tokens <= 0
+        ):
+            raise ValueError(
+                "ClaudeEngine.config['max_tokens'] must be a positive integer."
+            )
+
+        return max_tokens
+
+    @staticmethod
+    def _previous_messages(
+        provider_state: dict[str, Any] | None,
+    ) -> list[dict[str, Any]]:
+        """Validate and return prior Anthropic messages."""
+        if provider_state is None:
+            return []
+
+        messages = provider_state.get("messages")
+        if not isinstance(messages, list) or not messages:
+            raise ValueError(
+                "Claude prepared provider state must contain a non-empty "
+                "'messages' list."
+            )
+
+        for message in messages:
+            if not isinstance(message, dict):
+                raise ValueError("Claude provider state messages must be dictionaries.")
+
+            if message.get("role") not in {"user", "assistant"}:
+                raise ValueError(
+                    "Claude provider state messages must have role 'user' "
+                    "or 'assistant'."
+                )
+
+            if "content" not in message:
+                raise ValueError(
+                    "Claude provider state messages must contain 'content'."
+                )
+
+        return copy.deepcopy(messages)

konen/backend/engine_factory.py

@@ -0,0 +1,87 @@
+from collections.abc import Callable
+from typing import Any, ClassVar
+
+from .claude_engine import ClaudeEngine
+from .gemini_engine import GeminiEngine
+from .gpt_engine import GPTEngine
+from .kimi_engine import KimiEngine
+from .llm_engine import LLMEngine
+
+
+class EngineFactory:
+    """Factory for provider-specific execution engines."""
+
+    _builders: ClassVar[dict[str, Callable[[dict[str, Any]], LLMEngine]]] = {}
+
+    @classmethod
+    def register(
+        cls, model_family: str, builder: Callable[[dict[str, Any]], LLMEngine]
+    ) -> None:
+        """Register a builder for a model family."""
+        cls._builders[model_family] = builder
+
+    @classmethod
+    def build(
+        cls,
+        model_family: str,
+        model_name: str,
+        config: dict[str, Any] | None = None,
+        uid: str | None = None,
+    ) -> LLMEngine:
+        """Build an engine for a model family."""
+        try:
+            builder = cls._builders[model_family]
+        except KeyError as exc:
+            raise ValueError(f"Unsupported model_family: '{model_family}'.") from exc
+        kwargs: dict[str, Any] = {
+            "model_family": model_family,
+            "model_name": model_name,
+        }
+        if config is not None:
+            kwargs["config"] = dict(config)
+        if uid is not None:
+            kwargs["uid"] = uid
+        return builder(kwargs)
+
+    @staticmethod
+    def _validate_builder_kwargs(kwargs: dict[str, Any]) -> None:
+        """Validate keyword arguments for an engine builder."""
+        allowed_keys = {"model_family", "model_name", "config", "uid"}
+        unexpected_keys = sorted(set(kwargs) - allowed_keys)
+        if unexpected_keys:
+            unexpected_keys_str = ", ".join(unexpected_keys)
+            raise ValueError(f"Unexpected engine kwargs: {unexpected_keys_str}.")
+
+    @staticmethod
+    def _claude_engine_builder(kwargs: dict[str, Any]) -> LLMEngine:
+        kwargs = dict(kwargs)
+        kwargs["model_family"] = "claude"
+        EngineFactory._validate_builder_kwargs(kwargs)
+        return ClaudeEngine(**kwargs)
+
+    @staticmethod
+    def _gemini_engine_builder(kwargs: dict[str, Any]) -> LLMEngine:
+        kwargs = dict(kwargs)
+        kwargs["model_family"] = "gemini"
+        EngineFactory._validate_builder_kwargs(kwargs)
+        return GeminiEngine(**kwargs)
+
+    @staticmethod
+    def _gpt_engine_builder(kwargs: dict[str, Any]) -> LLMEngine:
+        kwargs = dict(kwargs)
+        kwargs["model_family"] = "gpt"
+        EngineFactory._validate_builder_kwargs(kwargs)
+        return GPTEngine(**kwargs)
+
+    @staticmethod
+    def _kimi_engine_builder(kwargs: dict[str, Any]) -> LLMEngine:
+        kwargs = dict(kwargs)
+        kwargs["model_family"] = "kimi"
+        EngineFactory._validate_builder_kwargs(kwargs)
+        return KimiEngine(**kwargs)
+
+
+EngineFactory.register("claude", EngineFactory._claude_engine_builder)
+EngineFactory.register("gemini", EngineFactory._gemini_engine_builder)
+EngineFactory.register("gpt", EngineFactory._gpt_engine_builder)
+EngineFactory.register("kimi", EngineFactory._kimi_engine_builder)

konen/backend/engine_router.py

@@ -0,0 +1,43 @@
+from dataclasses import dataclass, field
+
+from .workspace import Workspace
+
+
+@dataclass(slots=True)
+class EngineRouter:
+    """Mapping from agent identifiers to engine identifiers."""
+
+    table: dict[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self.table = dict(self.table)
+
+    @classmethod
+    def from_workspace(cls, workspace: Workspace) -> "EngineRouter":
+        """Build a router from workspace configuration."""
+        mapping_data = workspace.load_agent_engine_map_config()
+        return cls(table=mapping_data["agent_engine_map"])
+
+    def assign_engine(self, agent_uid: str, engine_uid: str) -> None:
+        """Assign an engine to an agent."""
+        self.table[agent_uid] = engine_uid
+
+    def unassign_engine(self, agent_uid: str) -> None:
+        """Remove an agent's engine assignment."""
+        if agent_uid not in self.table:
+            raise ValueError(f"No engine mapping exists for agent '{agent_uid}'.")
+        del self.table[agent_uid]
+
+    def get_engine_uid(self, agent_uid: str) -> str:
+        """Return the engine identifier assigned to an agent."""
+        try:
+            return self.table[agent_uid]
+        except KeyError as exc:
+            raise ValueError(
+                f"No engine mapping exists for agent '{agent_uid}'."
+            ) from exc
+
+    def reload_from_workspace(self, workspace: Workspace) -> None:
+        """Reload the router from workspace configuration."""
+        router = self.from_workspace(workspace)
+        self.table = dict(router.table)

konen/backend/gemini_engine.py

@@ -0,0 +1,138 @@
+from dataclasses import dataclass
+from typing import Any
+
+from google import genai
+
+from .llm_engine import LLMEngine
+from .llm_response import LLMResponse
+
+
+@dataclass(slots=True)
+class GeminiEngine(LLMEngine):
+    """Google Gemini execution engine."""
+
+    def __post_init__(self) -> None:
+        if self.model_family != "gemini":
+            raise ValueError("GeminiEngine requires model_family='gemini'.")
+        super().__post_init__()
+
+    def _initialize_client(self) -> genai.Client:
+        api_key = self.config.get("api_key")
+        if api_key is None:
+            return genai.Client()
+        return genai.Client(api_key=api_key)
+
+    def generate_response(
+        self,
+        prompt: str,
+        system_instruction: str | None = None,
+        provider_state: dict[str, Any] | None = None,
+    ) -> LLMResponse:
+        """Generate a response with the Gemini Interactions API."""
+        generation_kwargs: dict[str, Any] = {
+            "model": self.model_name,
+            "input": prompt,
+            "store": True,
+        }
+
+        if system_instruction is not None:
+            generation_kwargs["system_instruction"] = system_instruction
+
+        previous_interaction_id = self._previous_interaction_id(provider_state)
+        if previous_interaction_id is not None:
+            generation_kwargs["previous_interaction_id"] = previous_interaction_id
+
+        generation_config: dict[str, Any] = {}
+
+        thinking_level = self.config.get("thinking_level")
+        if thinking_level is not None:
+            generation_config["thinking_level"] = thinking_level
+
+        if generation_config:
+            generation_kwargs["generation_config"] = generation_config
+
+        interaction = self.client.interactions.create(**generation_kwargs)
+
+        status = self._status_value(interaction.status)
+        if status is None:
+            raise RuntimeError("Gemini interaction did not return a status.")
+
+        metadata = self._build_response_metadata()
+        metadata["interaction_status"] = status
+
+        interaction_id = interaction.id
+        if interaction_id is not None:
+            metadata["provider_response_id"] = interaction_id
+
+        usage = interaction.usage
+        if usage is not None:
+            token_usage: dict[str, int] = {}
+
+            usage_fields = {
+                "input_token_count": usage.total_input_tokens,
+                "output_token_count": usage.total_output_tokens,
+                "total_token_count": usage.total_tokens,
+                "cached_token_count": usage.total_cached_tokens,
+                "thought_token_count": usage.total_thought_tokens,
+                "tool_use_token_count": usage.total_tool_use_tokens,
+            }
+
+            for name, value in usage_fields.items():
+                if value is not None:
+                    token_usage[name] = value
+
+            if token_usage:
+                metadata["token_usage"] = token_usage
+
+        if status in {"failed", "cancelled", "budget_exceeded"}:
+            raise RuntimeError(f"Gemini interaction ended with status '{status}'.")
+
+        if status in {"queued", "in_progress", "requires_action"}:
+            raise RuntimeError(
+                "Gemini interaction did not complete synchronously; "
+                f"status is '{status}'."
+            )
+
+        if status not in {"completed", "incomplete"}:
+            raise RuntimeError(f"Unexpected Gemini interaction status '{status}'.")
+
+        try:
+            text = interaction.output_text
+        except (ValueError, AttributeError):
+            text = None
+
+        next_provider_state: dict[str, Any] = {}
+
+        if status == "completed":
+            if not isinstance(interaction_id, str) or not interaction_id:
+                raise RuntimeError("Completed Gemini interaction did not return an ID.")
+
+            next_provider_state["interaction_id"] = interaction_id
+
+        return LLMResponse(
+            text=text, metadata=metadata, provider_state=next_provider_state
+        )
+
+    @staticmethod
+    def _previous_interaction_id(provider_state: dict[str, Any] | None) -> str | None:
+        """Validate and return the previous Gemini interaction identifier."""
+        if provider_state is None:
+            return None
+
+        interaction_id = provider_state.get("interaction_id")
+
+        if not isinstance(interaction_id, str) or not interaction_id:
+            raise ValueError(
+                "Gemini provider state must contain a non-empty "
+                "'interaction_id' string."
+            )
+
+        return interaction_id
+
+    @staticmethod
+    def _status_value(status: Any) -> str | None:
+        """Return the Gemini interaction status value."""
+        if status is None:
+            return None
+
+        return getattr(status, "value", str(status))