kimix 0.1.0__tar.gz

kimix-0.1.0/.agents/skills/api/SKILL.md

@@ -0,0 +1,393 @@
+---
+name: api
+description: Guide for using Kimi API utilities (session management, prompts, RAG, colorful printing, threading)
+---
+
+# Kimi API Utilities Guide
+
+This guide explains how to use the utility functions from `kimi_utils.py` and `agent_utils.py` for session management, prompting, RAG search, colorful printing, and threading.
+
+## Session Management (kimi_utils.py)
+
+### create_session
+
+Create a new or resume an existing Kimi session.
+
+```python
+from kimi_utils import create_session
+from kaos.path import KaosPath
+
+# Create a new session
+session = create_session(
+    session_id="my_session",           # Optional: unique session identifier
+    work_dir=KaosPath("./workspace"),  # Optional: working directory
+    skills_dir=None,                   # Optional: KaosPath to skills directory
+    ralph_loop=None,                   # Optional: True/-1=unlimited, False/0=disabled
+    thinking=True,                     # Optional: enable deep thinking
+    yolo=True,                         # Optional: enable yolo mode (auto-approve)
+    plan_mode=False,                   # Optional: enable plan mode
+    resume=False,                      # Optional: resume existing session
+    agent_file=None,                   # Optional: Path to custom agent_worker.yaml
+    provider_dict=None                 # Optional: custom LLM provider config dict
+)
+
+# Close session when done
+from kimi_utils import close_session
+close_session(session)
+```
+
+### Default Session
+
+```python
+from kimi_utils import get_default_session, _create_default_session
+
+# Get or create the global default session (session_id="default")
+session = _create_default_session(resume=True)
+
+# Get existing default session without creating
+session = get_default_session()
+```
+
+### prompt / prompt_async
+
+Send a prompt to the Kimi agent and get a response.
+
+```python
+from kimi_utils import prompt, prompt_async
+
+# Simple prompt
+prompt("What is the capital of France?")
+
+# With options
+prompt(
+    "Analyze this code",
+    session=session,                   # Optional: use specific session (False=temp session)
+    read_agents_md=True,               # Optional: read AGENTS.md first if context is fresh
+    skill_name="python",               # Optional: enable skill (str or list of str)
+    output_function=custom_print,      # Optional: custom output handler for text chunks
+    info_print=True                    # Optional: print context usage after completion
+)
+
+# Async version (coroutine)
+await prompt_async("Analyze this code", session=session)
+```
+
+### validate
+
+Validate a condition using the agent. Appends "If the condition is true, run `Setflag` tool." internally.
+
+```python
+from kimi_utils import validate
+
+# Returns True if agent calls Setflag, False otherwise
+result = validate("Check if the file exists and contains 'TODO'")
+```
+
+### Context Management
+
+```python
+from kimi_utils import clear_context, print_usage, delete_session_dir
+
+# Clear current context and start fresh
+clear_context(force_create=True, resume=True, print_info=True)
+
+# Print current context usage
+print_usage(session)
+
+# Delete all session directories (~/.kimi/sessions)
+delete_session_dir()
+```
+
+### Tool Call Errors
+
+```python
+from kimi_utils import get_tool_call_errors
+
+# Get and clear failed tool calls for a session
+errors = get_tool_call_errors(session)  # or session_id string
+# Returns formatted string: function, arguments, output, message
+```
+
+### Session Settings
+
+```python
+from kimi_utils import set_plan_mode, clear_context
+
+# Toggle plan mode (clears context automatically)
+set_plan_mode(True)
+```
+
+## RAG Search (kimi_utils.py)
+
+Perform semantic search on files using `TextSearchIndex` with an LRU cache (max 3 indices).
+
+```python
+from kimi_utils import rag
+
+# Basic search
+results = rag(
+    query="authentication middleware",
+    file_path="./src",                 # Optional: path to search (default: current dir)
+    top_k=5,                           # Optional: number of results (default: 5)
+    content=False,                     # Optional: include full file content in results
+    refresh=False,                     # Optional: force re-index
+    hybrid_search=True,                # Optional: hybrid semantic + keyword search
+    negative="deprecated"              # Optional: keywords to penalize
+)
+
+# Process results
+for result in results:
+    print(f"File: {result.file_path}")
+    print(f"Score: {result.score}")
+    if hasattr(result, 'full_content'):
+        print(f"Content: {result.full_content[:200]}...")
+```
+
+## Colorful Printing (agent_utils.py)
+
+### Basic Print Functions
+
+```python
+from agent_utils import (
+    print_success,    # Green bold - success messages
+    print_error,      # Red bold - error messages
+    print_warning,    # Yellow bold - warning messages
+    print_info,       # Magenta - info messages
+    print_debug,      # Cyan - debug messages (silent if _quiet=True)
+    print_string,     # Plain text (respects _print_func)
+)
+
+# Usage
+print_success("Operation completed successfully!")
+print_error("File not found: config.yaml")
+print_warning("This feature is deprecated.")
+print_info("Processing step 3 of 5...")
+print_debug("Variable x = 42")
+```
+
+### Advanced Color Printing
+
+```python
+from agent_utils import colorful_print, Color, BgColor, Style
+
+# Full control over colors and styles
+colorful_print(
+    "Important message!",
+    fg=Color.BRIGHT_RED,
+    bg=BgColor.YELLOW,
+    styles=[Style.BOLD, Style.UNDERLINE]
+)
+
+# Available colors
+# Foreground: BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE
+#             BRIGHT_BLACK, BRIGHT_RED, BRIGHT_GREEN, BRIGHT_YELLOW
+#             BRIGHT_BLUE, BRIGHT_MAGENTA, BRIGHT_CYAN, BRIGHT_WHITE
+# Background: Same pattern with BgColor
+# Styles: RESET, BOLD, DIM, ITALIC, UNDERLINE, BLINK, REVERSE, HIDDEN, STRIKETHROUGH
+```
+
+### Print Agent JSON
+
+```python
+from agent_utils import print_agent_json
+
+# Pretty-print streaming messages from the agent session
+print_agent_json(
+    get_message=lambda: message.model_dump_json(),
+    output_function=custom_handler  # Optional: callback for text content
+)
+```
+
+## Threading (agent_utils.py)
+
+### Running Functions in Background
+
+```python
+from agent_utils import run_thread, sync_all
+
+# Run function in background thread (max 4 concurrent)
+def my_task(data):
+    # Long running operation
+    process(data)
+
+thread = run_thread(my_task, (data,))
+
+# Wait for all threads to complete
+sync_all()
+```
+
+### Async Prompt Helpers
+
+```python
+from kimi_utils import async_prompt, async_fix_error
+
+# Run prompt in background thread
+thread = async_prompt("Analyze this file", session=False)
+
+# Run fix_error in background thread
+thread = async_fix_error("python main.py", extra_prompt="Handle edge cases")
+```
+
+### Process Execution
+
+```python
+from agent_utils import _run_process_with_log, run_process_with_error, run_script
+
+# Run command and capture output
+output, returncode = _run_process_with_log("ls -la")
+
+# Run command and capture only errors
+error_output = run_process_with_error(
+    command="npm run build",
+    keycode=("error", "failed"),     # Keywords to look for in output
+    skip_success=True                # Return None if no error keywords found and code==0
+)
+
+# Run a Python script in a new console window
+proc = run_script("./script.py")
+```
+
+## File Operations (kimi_utils.py)
+
+```python
+from kimi_utils import read_file, prompt_path
+from pathlib import Path
+
+# Read file content
+content = read_file(Path("config.yaml"))
+
+# Read and split by delimiter
+sections = read_file(Path("docs.txt"), split_word="===SECTION===")
+
+# Prompt with file content
+prompt_path(Path("instructions.txt"))
+
+# Prompt with split content and optional coroutine callback
+prompt_path(
+    Path("tasks.txt"),
+    split_word="---",
+    after_prompt_coro=generator_func  # Optional: generator called after each chunk
+)
+```
+
+## Error Fix Loop (kimi_utils.py)
+
+```python
+from kimi_utils import fix_error
+
+# Automatically detect and fix errors from a command
+fix_error(
+    command="python main.py",
+    extra_prompt="Make sure to handle edge cases",  # Optional: extra instructions
+    keycode=("error", "exception"),                  # Optional: keywords to detect
+    skip_success=True,                               # Optional: skip if return code is 0
+    session=None,                                    # Optional: session to use
+    max_loop=4                                       # Optional: max fix attempts
+)
+```
+
+## Configuration Variables (agent_utils.py)
+
+Default configuration values you can import and modify:
+
+```python
+from agent_utils import (
+    _default_thinking,       # Deep thinking mode (default: True)
+    _default_plan_mode,      # Plan mode (default: False)
+    _default_yolo,           # Yolo mode (default: True)
+    _default_agent_file,     # Path to agent_worker.yaml
+    _default_skill_dirs,     # List of skill directories
+    _default_provider,       # Custom provider dict or None
+    _quiet,                  # If True, suppresses print_debug
+    _colorful_print,         # If False, disables ANSI colors
+    _print_func,             # Optional custom print handler (text, end) -> None
+)
+```
+
+### Skill Directories
+
+```python
+from agent_utils import get_skill_dirs
+
+# Auto-discover skill directories (checked paths: .agents/skills, .config/.agents/skills, .opencode/skills)
+dirs = get_skill_dirs(use_kaos_path=True)
+```
+
+## Complete Example
+
+```python
+"""Example script using Kimi API utilities."""
+from pathlib import Path
+from kimi_utils import create_session, prompt, rag, close_session, clear_context
+from agent_utils import print_success, print_error, print_info
+
+# Create session
+session = create_session(
+    session_id="example",
+    thinking=True,
+    yolo=True
+)
+
+try:
+    # Search for relevant code
+    print_info("Searching for authentication code...")
+    results = rag(
+        query="auth middleware",
+        file_path="./src",
+        top_k=3,
+        content=True
+    )
+    
+    # Build context from results
+    context = "\n\n".join([r.full_content for r in results if hasattr(r, 'full_content')])
+    
+    # Prompt with context
+    prompt(
+        f"Review this authentication code:\n\n{context}",
+        session=session
+    )
+    
+    print_success("Analysis complete!")
+    
+except Exception as e:
+    print_error(f"Error: {e}")
+    
+finally:
+    close_session(session)
+```
+
+## Best Practices
+
+1. **Always close sessions** - Use `close_session()` when done to free resources
+2. **Use colorful prints** - Makes output more readable and organized
+3. **Handle errors** - Wrap prompts in try/except blocks
+4. **Leverage RAG** - Use `rag()` for finding relevant code/context
+5. **Background tasks** - Use `run_thread()` for long-running operations
+6. **Session reuse** - Reuse sessions for related prompts to save context
+7. **Clear context** - Call `clear_context()` when switching topics
+8. **Validate conditions** - Use `validate()` for yes/no checks via the agent
+9. **Fix errors automatically** - Use `fix_error()` for iterative debugging
+10. **Skill directories** - Place skills in `.agents/skills/` for auto-discovery
+
+## Common Imports
+
+```python
+# Core utilities
+from kimi_utils import (
+    create_session, close_session, prompt, prompt_async,
+    validate, rag, clear_context, print_usage,
+    get_default_session, get_tool_call_errors,
+    set_plan_mode,
+    read_file, prompt_path, fix_error, async_prompt
+)
+from agent_utils import (
+    print_success, print_error, print_warning,
+    print_info, print_debug, colorful_print,
+    Color, BgColor, Style, run_thread, sync_all,
+    run_process_with_error, get_skill_dirs
+)
+
+# Standard library
+from pathlib import Path
+import asyncio
+```

kimix-0.1.0/.agents/skills/tool/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: tool
+description: Guide for creating tools using CallableTool2 and Params pattern
+---
+
+# Tool Development Guide
+
+This guide explains how to create custom tools using the `CallableTool2` and `Params` pattern.
+
+## Quick Template
+
+```python
+"""Brief description of what this tool does."""
+from kimi_agent_sdk import CallableTool2, ToolError, ToolOk, ToolReturnValue
+from pydantic import BaseModel, Field
+
+
+class Params(BaseModel):
+    """Define tool parameters here."""
+    required_param: str = Field(
+        description="Description of this parameter for the LLM."
+    )
+    optional_param: str | None = Field(
+        default=None,
+        description="Optional parameter with default value."
+    )
+
+
+class MyTool(CallableTool2):
+    name: str = "MyTool"              # Tool identifier
+    description: str = "What this tool does."  # For LLM to understand usage
+    params: type[Params] = Params     # Link to Params class
+
+    async def __call__(self, params: Params) -> ToolReturnValue:
+        """Execute the tool logic."""
+        try:
+            # Your tool logic here
+            result = f"Processed: {params.required_param}"
+            return ToolOk(output=result)
+        except Exception as e:
+            return ToolError(
+                message=str(e),
+                output="Partial output if available",
+                brief="Short error summary"
+            )
+```
+
+## Complete Example
+
+```python
+"""Fetch and process web content."""
+import asyncio
+import aiohttp
+from kimi_agent_sdk import CallableTool2, ToolError, ToolOk, ToolReturnValue
+from pydantic import BaseModel, Field
+
+
+class Params(BaseModel):
+    """Parameters for web fetch tool."""
+    url: str = Field(
+        description="URL to fetch content from."
+    )
+    timeout: float | None = Field(
+        default=30.0,
+        ge=1,
+        le=300,
+        description="Request timeout in seconds (1-300)."
+    )
+    max_length: int | None = Field(
+        default=10000,
+        description="Maximum content length to return."
+    )
+
+
+class WebFetch(CallableTool2):
+    """Fetch web page content."""
+    name: str = "WebFetch"
+    description: str = "Fetch content from a URL with optional timeout and length limits."
+    params: type[Params] = Params
+
+    async def __call__(self, params: Params) -> ToolReturnValue:
+        """Fetch URL content asynchronously."""
+        try:
+            async with aiohttp.ClientSession() as session:
+                async with session.get(
+                    params.url, 
+                    timeout=aiohttp.ClientTimeout(total=params.timeout)
+                ) as response:
+                    content = await response.text()
+                    
+                    # Apply length limit
+                    if len(content) > params.max_length:
+                        content = content[:params.max_length] + "\n... (truncated)"
+                    
+                    return ToolOk(output=content)
+                    
+        except asyncio.TimeoutError:
+            return ToolError(
+                message=f"Request timed out after {params.timeout}s",
+                output="",
+                brief="Timeout error"
+            )
+        except Exception as e:
+            return ToolError(
+                message=str(e),
+                output="",
+                brief="Fetch failed"
+            )
+```
+
+## Params Class Reference
+
+### Field Types
+
+| Pattern | Description | Example |
+|---------|-------------|---------|
+| `param: str` | Required string | `path: str = Field(description="File path.")` |
+| `param: str \| None` | Optional string | `cwd: str \| None = Field(default=None, ...)` |
+| `param: list[str]` | List of strings | `args: list[str] = Field(default_factory=list, ...)` |
+| `param: bool` | Boolean flag | `force: bool = Field(default=False, ...)` |
+| `param: int \| float` | Numeric | `timeout: float = Field(default=30, ge=0)` |
+
+### Field Validators
+
+Use these in `Field()` for validation:
+
+```python
+# Numeric constraints
+ge=0          # Greater than or equal to 0
+le=100        # Less than or equal to 100
+gt=0          # Greater than 0
+lt=100        # Less than 100
+
+# String constraints
+min_length=1  # Minimum string length
+max_length=255  # Maximum string length
+pattern=r"^\d+$"  # Regex pattern
+
+# Collection constraints
+min_length=1  # Minimum list/dict items
+max_length=10  # Maximum list/dict items
+```
+
+### Default Values
+
+```python
+# Simple default
+timeout: int = Field(default=30, ...)
+
+# Factory default (for mutable types like list, dict)
+args: list[str] = Field(default_factory=list, ...)
+env: dict[str, str] = Field(default_factory=dict, ...)
+
+# Optional with None default
+output_path: str | None = Field(default=None, ...)
+```
+
+## CallableTool2 Class Rules
+
+### Required Attributes
+
+```python
+class MyTool(CallableTool2):
+    name: str = "MyTool"                    # Unique identifier
+    description: str = "Does something."    # LLM-visible description
+    params: type[Params] = Params           # Must reference Params class
+```
+
+### The __call__ Method
+
+```python
+async def __call__(self, params: Params) -> ToolReturnValue:
+    """
+    Args:
+        params: Instance of your Params class with validated values
+    
+    Returns:
+        ToolOk(output="success result") on success
+        ToolError(message="...", output="...", brief="...") on failure
+    """
+```
+
+### Return Values
+
+**Success:**
+```python
+return ToolOk(output="Your result here")
+```
+
+**Error:**
+```python
+return ToolError(
+    message="Full error details for debugging",
+    output="Partial output if any was produced",
+    brief="Short error summary for display"
+)
+```
+
+## Best Practices
+
+1. **Always use type hints** - Both for Params fields and __call__ return type
+2. **Write clear descriptions** - LLM uses Field descriptions to understand parameters
+3. **Use proper defaults** - `default_factory=list` for lists, `default=None` for optionals
+4. **Handle exceptions** - Wrap logic in try/except and return ToolError
+5. **Make it async** - __call__ should always be async for consistency
+6. **Validate inputs** - Use Field validators (ge, le, min_length, etc.)
+7. **Keep it focused** - One tool should do one thing well
+8. **Document with docstrings** - Module, class, and method docstrings
+
+## Common Imports
+
+```python
+# Core imports (always needed)
+from kimi_agent_sdk import CallableTool2, ToolError, ToolOk, ToolReturnValue
+from pydantic import BaseModel, Field
+
+# Common stdlib imports
+import asyncio
+import os
+from pathlib import Path
+from typing import Any
+
+# For subprocess tools
+import subprocess
+import threading
+```
+
+## File Naming
+
+Place your tool in the appropriate module:
+- `my_tools/py/__init__.py` - Python execution tools
+- `my_tools/file/run.py` - File/process tools
+- `my_tools/<category>/<tool_name>.py` - Organize by category
+
+## Background Task Tools Reference
+
+The `my_tools/background/` module provides tools for managing background tasks:
+
+### Tool Classes
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `TaskList` | List all background tasks with their status | None |
+| `TaskOutput` | Get accumulated output from a background task | `task_id: str` |
+| `TaskWait` | Wait for a background task to complete | `task_id: str` |
+
+### Utility Classes and Functions
+
+**BackgroundStream** (`utils.py`)
+A wrapper for background thread execution with a thread-safe queue:
+- `start(function)` - Start the background thread with a given function that accepts a `queue.Queue[str]`
+- `wait()` - Wait for the background thread to complete
+- `pop_output()` - Retrieve and clear all output from the queue
+- `get_output()` - Retrieve all output from the queue without clearing
+- `get_queue()` - Get the thread-safe queue for retrieving messages
+- `is_started()` - Check if the stream has been started
+
+**Task Management Functions** (`utils.py`)
+- `generate_task_id(kind, name=None)` - Generate a unique task ID
+- `add_task(task_id, stream)` - Register a task with its BackgroundStream
+- `remove_task_id(task_id)` - Remove a task ID from the global registry
+- `get_all_tasks()` - Get all registered tasks as a dict
+
+### Usage Example
+
+```python
+from my_tools.background.utils import (
+    generate_task_id, add_task, BackgroundStream
+)
+
+# Create and start a background task
+stream = BackgroundStream()
+task_id = generate_task_id("download", "file1")
+stream.start(my_background_function, stop_function)
+add_task(task_id, stream)
+
+# Later, use tools to interact with the task:
+# - TaskList: List all running tasks
+# - TaskOutput: Get output from a specific task
+# - TaskWait: Wait for a task to complete
+```

kimix-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__
+agent.py
+kaos/
+kimi_agent_sdk/
+kimi_cli/
+kosong/
+requirements.txt
+.cache
+.index_cache
+uv.lock
+clone_submodule.py

kimix-0.1.0/.gitmodules

@@ -0,0 +1,6 @@
+[submodule "kimi-cli"]
+	path = kimi-cli
+	url = https://github.com/MaxwellGengYF/kimi-cli.git
+[submodule "kimi-agent-sdk"]
+	path = kimi-agent-sdk
+	url = https://github.com/MaxwellGengYF/kimi-agent-sdk.git

kimix-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.8.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [types-all]
+        args: [--strict, --ignore-missing-imports]

kimix-0.1.0/AGENTS.md

@@ -0,0 +1,8 @@
+# Rules:
+
+After writing any Python script, run:
+```bash
+uv run tools/syntax_check.py <python_file_name>
+```
+Fix all errors reported by the syntax checker before proceeding.
+use `uv run tools/git_diff.py` to check file diff.