kora-agent 0.1.0__py3-none-any.whl

kora/__init__.py

@@ -0,0 +1,31 @@
+"""
+Kora - A lightweight Agent framework.
+"""
+
+from kora._version import __version__
+from kora.runtime import Agent, Session
+from kora.tools import tool
+
+# Providers
+from kora.providers import (
+    Model,
+    ModelSpec,
+    ModelCost,
+    Provider,
+    ProviderSpec,
+    get_provider_registry,
+)
+
+__all__ = [
+    "__version__",
+    "Agent",
+    "Session",
+    "tool",
+    # Providers
+    "Model",
+    "ModelSpec",
+    "ModelCost",
+    "Provider",
+    "ProviderSpec",
+    "get_provider_registry",
+]

kora/_version.py

@@ -0,0 +1,3 @@
+"""Version information for Kora."""
+
+__version__ = "0.1.0"

kora/cli.py

@@ -0,0 +1,349 @@
+"""
+CLI for Kora Agent Framework.
+
+Provides commands to run agents:
+- kora run --agent <path> "message"  # One-shot execution
+- kora code "message"                 # One-shot with kora-code agent
+- kora code                           # Interactive REPL mode
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from kora.host import (
+    setup_agent,
+    AgentSetup,
+    find_builtin_agent,
+    load_agent_commands,
+    ReplRuntime,
+    create_default_registry,
+)
+from kora.interface import (
+    ConsoleRenderer,
+    print_command_menu,
+    create_repl_input,
+    HAS_PROMPT_TOOLKIT,
+    render_markdown_lite,
+)
+
+
+def run_agent(
+    agent_path: Path,
+    workspace: Path,
+    user_message: str,
+    *,
+    provider: str | None = None,
+    model: str | None = None,
+    session_id: str | None = None,
+) -> int:
+    """
+    Run an agent with a single message (one-shot mode).
+
+    Args:
+        agent_path: Path to AGENT.md file.
+        workspace: Workspace directory for file operations.
+        user_message: The task or question for the agent.
+        provider: Model provider override.
+        model: Model name override.
+        session_id: Optional session ID to resume.
+
+    Returns:
+        Exit code (0 for success, 1 for error).
+    """
+    # Setup agent (Host layer)
+    setup = setup_agent(agent_path, workspace, provider=provider, model=model)
+    if setup is None:
+        print(f"Error: Failed to setup agent from {agent_path}", file=sys.stderr)
+        return 1
+
+    agent = setup.agent
+
+    # Open or resume session
+    if session_id:
+        session = agent.load_session(session_id)
+        if session is None:
+            print(f"Session {session_id} not found, creating new session")
+            session = agent.open_session(session_id=session_id)
+    else:
+        session = agent.open_session()
+
+    print(f"Workspace: {setup.workspace_id}")
+    print(f"Session: {session.id}")
+
+    # Use ConsoleRenderer for verbose one-shot mode
+    renderer = ConsoleRenderer(verbose=True)
+
+    # Run
+    session.send_sync(
+        user_message,
+        on_event=lambda e: _print_rendered(renderer.render(e))
+    )
+
+    # Save session after execution
+    session.save()
+
+    return 0
+
+
+def _print_rendered(output: str | None) -> None:
+    """Print rendered output if not None."""
+    if output:
+        print(output)
+
+
+def run_repl(
+    agent_path: Path,
+    workspace: Path,
+    *,
+    provider: str | None = None,
+    model: str | None = None,
+    session_id: str | None = None,
+) -> int:
+    """
+    Run an agent in interactive REPL mode.
+
+    Args:
+        agent_path: Path to AGENT.md file.
+        workspace: Workspace directory for file operations.
+        provider: Model provider override.
+        model: Model name override.
+        session_id: Optional session ID to resume.
+
+    Returns:
+        Exit code (0 for success, 1 for error).
+    """
+    # Setup agent (Host layer)
+    setup = setup_agent(agent_path, workspace, provider=provider, model=model)
+    if setup is None:
+        print(f"Error: Failed to setup agent from {agent_path}", file=sys.stderr)
+        return 1
+
+    agent = setup.agent
+    context_builder = setup.context_builder
+    provider_name = setup.provider_name
+    model_name = setup.model_name
+    workspace_id = setup.workspace_id
+
+    # Open or resume session
+    if session_id:
+        session = agent.load_session(session_id)
+        if session is None:
+            print(f"Session {session_id} not found, creating new session")
+            session = agent.open_session(session_id=session_id)
+    else:
+        session = agent.open_session()
+
+    # Create command registry and load agent extensions (ADR-010)
+    registry = create_default_registry()
+    loaded_count = load_agent_commands(setup.agent_package.path, registry)
+    if loaded_count > 0:
+        print(f"   Loaded {loaded_count} custom command(s)")
+
+    # Create ReplRuntime - encapsulates all REPL logic (Host layer)
+    runtime = ReplRuntime(
+        session=session,
+        agent=agent,
+        context_builder=context_builder,
+        provider_name=provider_name,
+        model_name=model_name,
+        registry=registry,
+    )
+
+    # Use ConsoleRenderer for compact REPL mode
+    renderer = ConsoleRenderer(verbose=False)
+
+    # Print welcome message
+    print(f"\n🤖 Kora Code Agent")
+    print(f"   Workspace: {workspace_id}")
+    print(f"   Session: {session.id}")
+    print(f"   Model: {provider_name}/{model_name}")
+    print(f"   Workspace path: {workspace}")
+    print(f"\nType your message and press Enter. Type '/' to see commands.\n")
+
+    # Run REPL loop (Interface layer handles input)
+    return _run_repl(session, agent, runtime, renderer, registry)
+
+
+def _run_repl(
+    session,
+    agent,
+    runtime: ReplRuntime,
+    renderer: ConsoleRenderer,
+    registry,
+) -> int:
+    """
+    Run REPL loop using interface layer for input.
+
+    Uses prompt_toolkit if available for auto-completion,
+    otherwise falls back to basic input.
+    """
+    # Create input handler from interface layer
+    repl_input = create_repl_input(registry)
+
+    try:
+        while True:
+            try:
+                # Add a blank line for visual breathing before input
+                user_input = repl_input.get_input("\n> ").strip()
+
+                if not user_input:
+                    continue
+
+                # Basic REPL: show menu when user types just "/"
+                if not HAS_PROMPT_TOOLKIT and user_input == "/":
+                    print_command_menu(registry)
+                    continue
+
+                # Delegate command handling to ReplRuntime (Host layer)
+                result = runtime.execute_command(user_input)
+                if result is not None:
+                    if runtime.is_exit_requested(result):
+                        print(f"\n{render_markdown_lite(result.message)}")
+                        break
+                    prefix = "✅" if result.status == "ok" else "❌"
+                    print(f"\n{render_markdown_lite(result.message)}")
+                    continue
+
+                # Normal message to agent
+                session.send_sync(
+                    user_input,
+                    on_event=lambda e: _print_rendered(renderer.render(e))
+                )
+                session.save()
+
+            except KeyboardInterrupt:
+                print("\n\n👋 Session saved. Bye!")
+                break
+            except EOFError:
+                print("\n\n👋 Session saved. Bye!")
+                break
+
+    except Exception as e:
+        print(f"\n❌ Unexpected error: {e}", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+def main() -> int:
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        prog="kora",
+        description="Kora Agent Framework",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # kora run --agent <path> [message]
+    run_parser = subparsers.add_parser("run", help="Run an agent from AGENT.md")
+    run_parser.add_argument(
+        "--agent",
+        type=Path,
+        required=True,
+        help="Path to AGENT.md file",
+    )
+    run_parser.add_argument(
+        "--workspace",
+        type=Path,
+        default=Path.cwd(),
+        help="Workspace directory (default: current directory)",
+    )
+    run_parser.add_argument(
+        "--provider",
+        help="Model provider (e.g., anthropic, openai, deepseek)",
+    )
+    run_parser.add_argument(
+        "--model",
+        help="Model name (e.g., claude-sonnet-4-20250514, gpt-4o)",
+    )
+    run_parser.add_argument(
+        "--session",
+        help="Resume a session by ID",
+    )
+    run_parser.add_argument(
+        "message",
+        nargs="?",
+        help="Task or question for the agent (omit for REPL mode)",
+    )
+
+    # kora code [message]
+    code_parser = subparsers.add_parser("code", help="Run Kora Code Agent")
+    code_parser.add_argument(
+        "--workspace",
+        type=Path,
+        default=Path.cwd(),
+        help="Workspace directory (default: current directory)",
+    )
+    code_parser.add_argument(
+        "--provider",
+        help="Model provider (e.g., anthropic, openai, deepseek)",
+    )
+    code_parser.add_argument(
+        "--model",
+        help="Model name (e.g., claude-sonnet-4-20250514, gpt-4o)",
+    )
+    code_parser.add_argument(
+        "--session",
+        help="Resume a session by ID",
+    )
+    code_parser.add_argument(
+        "message",
+        nargs="?",
+        help="Task or question for the agent (omit for REPL mode)",
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "run":
+        agent_path = args.agent
+        if args.message:
+            return run_agent(
+                agent_path=agent_path,
+                workspace=args.workspace,
+                user_message=args.message,
+                provider=args.provider,
+                model=args.model,
+                session_id=args.session,
+            )
+        else:
+            return run_repl(
+                agent_path=agent_path,
+                workspace=args.workspace,
+                provider=args.provider,
+                model=args.model,
+                session_id=args.session,
+            )
+
+    elif args.command == "code":
+        agent_dir = find_builtin_agent("kora-code")
+        if agent_dir is None:
+            print("Error: Kora Code Agent not found", file=sys.stderr)
+            print("Install it:  pip install kora-agent kora-code", file=sys.stderr)
+            print("Or:          pip install kora-agent[code]", file=sys.stderr)
+            return 1
+
+        if args.message:
+            return run_agent(
+                agent_path=agent_dir,
+                workspace=args.workspace,
+                user_message=args.message,
+                provider=args.provider,
+                model=args.model,
+                session_id=args.session,
+            )
+        else:
+            return run_repl(
+                agent_path=agent_dir,
+                workspace=args.workspace,
+                provider=args.provider,
+                model=args.model,
+                session_id=args.session,
+            )
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

kora/host/__init__.py

@@ -0,0 +1,166 @@
+"""
+Host layer for Kora.
+
+The host layer manages persistence, file system access, identity, and resources.
+"""
+
+from kora.host.loader import (
+    AgentConfigYaml,
+    AgentPackage,
+    load_agent_from_markdown,
+    load_agent_package,
+    load_agent_commands,
+    load_agent_interactions,
+    find_builtin_agent,
+)
+from kora.host.storage import (
+    FileStorage,
+    FileStorageConfig,
+    RunState,
+    Storage,
+)
+from kora.host.identity import (
+    User,
+    IdentityResolver,
+    EnvIdentityResolver,
+    StaticIdentityResolver,
+    DefaultUserResolver,
+)
+from kora.host.workspace import (
+    WorkspaceBinding,
+    WorkspaceResolver,
+)
+from kora.host.permission import (
+    Permission,
+    PermissionDeniedError,
+    PermissionPolicy,
+    HostPermissionPolicy,
+    PermissivePolicy,
+    CompositePolicy,
+    create_default_policy,
+)
+from kora.host.instructions import (
+    InstructionScope,
+    InstructionSource,
+    TemplateContext,
+    InstructionComposer,
+    resolve_instruction_sources,
+)
+from kora.host.commands import (
+    CommandResult,
+    CommandContext,
+    CommandRegistry,
+    create_default_registry,
+    HelpCommand,
+    ClearCommand,
+    ExitCommand,
+    SessionCommand,
+    ModelCommand,
+    ModeCommand,
+    ContextCommand,
+    ResetCommand,
+    ReplAction,
+    VALID_MODES,
+    MODE_DESCRIPTIONS,
+)
+from kora.host.interactions import (
+    InteractionKind,
+    InteractionOption,
+    InteractionRequest,
+    InteractionResponse,
+    InteractionContext,
+    Interaction,
+    InteractionRegistry,
+    ChoiceInteraction,
+    ConfirmInteraction,
+    InputInteraction,
+    MenuInteraction,
+    create_default_registry as create_default_interaction_registry,
+)
+from kora.host.context import (
+    ContextRebuilder,
+)
+from kora.host.repl import (
+    ReplState,
+    ReplRuntime,
+)
+from kora.host.runner import (
+    AgentSetup,
+    setup_agent,
+)
+
+__all__ = [
+    # Agent loading
+    "load_agent_from_markdown",
+    "load_agent_package",
+    "load_agent_commands",
+    "load_agent_interactions",
+    "find_builtin_agent",
+    "AgentConfigYaml",
+    "AgentPackage",
+    # Storage
+    "Storage",
+    "FileStorage",
+    "FileStorageConfig",
+    "RunState",
+    # Identity
+    "User",
+    "IdentityResolver",
+    "EnvIdentityResolver",
+    "StaticIdentityResolver",
+    "DefaultUserResolver",
+    # Workspace
+    "WorkspaceBinding",
+    "WorkspaceResolver",
+    # Permission
+    "Permission",
+    "PermissionDeniedError",
+    "PermissionPolicy",
+    "HostPermissionPolicy",
+    "PermissivePolicy",
+    "CompositePolicy",
+    "create_default_policy",
+    # Instructions
+    "InstructionScope",
+    "InstructionSource",
+    "TemplateContext",
+    "InstructionComposer",
+    "resolve_instruction_sources",
+    # Commands
+    "CommandResult",
+    "CommandContext",
+    "CommandRegistry",
+    "create_default_registry",
+    "HelpCommand",
+    "ClearCommand",
+    "ExitCommand",
+    "SessionCommand",
+    "ModelCommand",
+    "ModeCommand",
+    "ContextCommand",
+    "ResetCommand",
+    "ReplAction",
+    "VALID_MODES",
+    "MODE_DESCRIPTIONS",
+    # Interactions
+    "InteractionKind",
+    "InteractionOption",
+    "InteractionRequest",
+    "InteractionResponse",
+    "InteractionContext",
+    "Interaction",
+    "InteractionRegistry",
+    "ChoiceInteraction",
+    "ConfirmInteraction",
+    "InputInteraction",
+    "MenuInteraction",
+    "create_default_interaction_registry",
+    # Context
+    "ContextRebuilder",
+    # REPL
+    "ReplState",
+    "ReplRuntime",
+    # Runner
+    "AgentSetup",
+    "setup_agent",
+]