konen 0.1.0__tar.gz

konen-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PolyShape P.C.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

konen-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: konen
+Version: 0.1.0
+Summary: Human-centered star-graph orchestration of AI agents
+Author: Theodore Papamarkou
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: anthropic
+Requires-Dist: google-genai>=2.18.1,<3.0.0
+Requires-Dist: jsonschema
+Requires-Dist: kimi-sdk
+Requires-Dist: openai
+Requires-Dist: prompt-toolkit
+Requires-Dist: rich
+Requires-Python: >=3.13, <3.16
+Project-URL: Source, https://github.com/polyshape/konen
+Project-URL: Documentation, https://polyshape.github.io/konen/
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/polyshape/konen/main/logo/konen_logo_transparent_bg.svg" alt="Konen logo" width="120">
+</p>
+
+# Konen: human-centered orchestration of AI agents
+
+*The Swiss army knife for agentic IREs*
+
+Konen is pronounced /ˈkoʊnɛn/. Its name comes from the star graph $K_{1,n}$, reflecting Konen's human-centered approach to agentic interaction. The human occupies the central node and orchestrates a collection of AI agents represented by the leaf nodes.
+
+Konen emphasizes human-directed deliberation. A user decides which agents participate and how they engage with each other's contributions, while maintaining a shared conversation history. Although similar capabilities exist in other multi-model tools, Konen offers a simple, focused approach suited to iterative exploration of ideas, critical analysis, and research. Thus, Konen is suited to use as an integrated research environment (IRE) for coordinating interactions across AI agents and model providers.
+
+## Installation
+
+Konen requires Python 3.13, 3.14, or 3.15.
+
+### pip
+
+Install Konen from PyPI:
+
+```bash
+pip install konen
+```
+
+### uv
+
+To install the CLI in an isolated environment:
+
+```bash
+uv tool install konen
+```
+
+Run `konen` after installing it. For a source checkout and development setup, see [DEVELOPMENT.md](https://github.com/polyshape/konen/blob/main/DEVELOPMENT.md).
+
+## Documentation
+
+Read the [documentation](https://polyshape.github.io/konen/), starting with the [first walkthrough example](https://polyshape.github.io/konen/examples/ai-consciousness-evidence.html).
+
+## License
+
+Konen is distributed under the MIT License. See [LICENSE](https://github.com/polyshape/konen/blob/main/LICENSE).

konen-0.1.0/README.md

@@ -0,0 +1,41 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/polyshape/konen/main/logo/konen_logo_transparent_bg.svg" alt="Konen logo" width="120">
+</p>
+
+# Konen: human-centered orchestration of AI agents
+
+*The Swiss army knife for agentic IREs*
+
+Konen is pronounced /ˈkoʊnɛn/. Its name comes from the star graph $K_{1,n}$, reflecting Konen's human-centered approach to agentic interaction. The human occupies the central node and orchestrates a collection of AI agents represented by the leaf nodes.
+
+Konen emphasizes human-directed deliberation. A user decides which agents participate and how they engage with each other's contributions, while maintaining a shared conversation history. Although similar capabilities exist in other multi-model tools, Konen offers a simple, focused approach suited to iterative exploration of ideas, critical analysis, and research. Thus, Konen is suited to use as an integrated research environment (IRE) for coordinating interactions across AI agents and model providers.
+
+## Installation
+
+Konen requires Python 3.13, 3.14, or 3.15.
+
+### pip
+
+Install Konen from PyPI:
+
+```bash
+pip install konen
+```
+
+### uv
+
+To install the CLI in an isolated environment:
+
+```bash
+uv tool install konen
+```
+
+Run `konen` after installing it. For a source checkout and development setup, see [DEVELOPMENT.md](https://github.com/polyshape/konen/blob/main/DEVELOPMENT.md).
+
+## Documentation
+
+Read the [documentation](https://polyshape.github.io/konen/), starting with the [first walkthrough example](https://polyshape.github.io/konen/examples/ai-consciousness-evidence.html).
+
+## License
+
+Konen is distributed under the MIT License. See [LICENSE](https://github.com/polyshape/konen/blob/main/LICENSE).

konen-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "konen"
+version = "0.1.0"
+description = "Human-centered star-graph orchestration of AI agents"
+readme = "README.md"
+requires-python = ">=3.13,<3.16"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = [
+    "anthropic",
+    "google-genai>=2.18.1,<3.0.0",
+    "jsonschema",
+    "kimi-sdk",
+    "openai",
+    "prompt-toolkit",
+    "rich",
+]
+
+[[project.authors]]
+name = "Theodore Papamarkou"
+
+[project.scripts]
+konen = "konen.cli.main:main"
+
+[project.urls]
+Source = "https://github.com/polyshape/konen"
+Documentation = "https://polyshape.github.io/konen/"
+
+[dependency-groups]
+dev = [
+    "ipykernel",
+    "pytest",
+    "ruff",
+]
+docs = [
+    "myst-parser",
+    "sphinx",
+]
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.lint]
+select = [
+    "E4",
+    "E7",
+    "E9",
+    "F",
+    "I",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.32,<0.12"]
+build-backend = "uv_build"

konen-0.1.0/pyproject.toml.orig

@@ -0,0 +1,49 @@
+[project]
+name = "konen"
+version = "0.1.0"
+description = "Human-centered star-graph orchestration of AI agents"
+readme = "README.md"
+authors = [
+    { name = "Theodore Papamarkou" }
+]
+requires-python = ">=3.13,<3.16"
+license = "MIT"
+license-files = ["LICENSE"]
+
+dependencies = [
+    "anthropic",
+    "google-genai>=2.18.1,<3.0.0",
+    "jsonschema",
+    "kimi-sdk",
+    "openai",
+    "prompt-toolkit",
+    "rich"
+]
+
+[project.scripts]
+konen = "konen.cli.main:main"
+
+[project.urls]
+Source = "https://github.com/polyshape/konen"
+Documentation = "https://polyshape.github.io/konen/"
+
+[dependency-groups]
+dev = [
+    "ipykernel",
+    "pytest",
+    "ruff"
+]
+docs = [
+    "myst-parser",
+    "sphinx"
+]
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I"]
+
+[build-system]
+requires = ["uv_build>=0.11.32,<0.12"]
+build-backend = "uv_build"

konen-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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)