kollabor 0.4.9__tar.gz

kollabor-0.4.9/CLAUDE.md

@@ -0,0 +1,369 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a **Kollabor CLI Interface** - an advanced, highly customizable terminal-based chat application for interacting with LLMs. The core principle is that **everything has hooks** - every action triggers customizable hooks that plugins can attach to for complete customization.
+
+## Architecture
+
+The application follows a modular, event-driven architecture:
+
+- **Core Application** (`core/application.py`): Main orchestrator that initializes all components
+- **Event System** (`core/events/`): Central event bus with hook system for plugins
+- **LLM Core** (`core/llm/`): Essential LLM services including API communication, conversation management, and tool execution
+- **I/O System** (`core/io/`): Terminal rendering, input handling, visual effects, and layout management
+- **Plugin System** (`core/plugins/`, `plugins/`): Dynamic plugin discovery and loading
+- **Storage** (`core/storage/`): State management and persistence
+- **Configuration** (`core/config/`): Flexible configuration management
+
+## Key Components
+
+### LLM Core Services (`core/llm/`)
+- `llm_service.py`: Main LLM orchestration service
+- `api_communication_service.py`: API communication with rate limiting
+- `conversation_logger.py`: Conversation persistence and logging (KollaborConversationLogger)
+- `conversation_manager.py`: Conversation state and history management
+- `tool_executor.py`: Tool/function calling execution
+- `hook_system.py`: LLM-specific hook management
+- `message_display_service.py`: Response formatting and display
+- `mcp_integration.py`: Model Context Protocol integration
+- `plugin_sdk.py`: Plugin development interface (KollaborPluginSDK)
+- `model_router.py`: Model selection and routing
+- `response_processor.py`: Response processing and formatting
+- `response_parser.py`: Response parsing utilities
+
+### Terminal I/O System (`core/io/`)
+- `terminal_renderer.py`: Main terminal rendering with status areas
+- `input_handler.py`: Raw mode input handling with key parsing
+- `layout.py`: Terminal layout management and thinking animations
+- `visual_effects.py`: Color palettes and visual effects
+- `status_renderer.py`: Multi-area status display system
+- `message_coordinator.py`: Message flow coordination
+- `message_renderer.py`: Message display rendering
+- `buffer_manager.py`: Terminal buffer management
+- `key_parser.py`: Keyboard input parsing
+- `terminal_state.py`: Terminal state management
+- `core_status_views.py`: Core status view implementations
+- `config_status_view.py`: Configuration status display
+
+### Plugin Architecture
+- Plugin discovery from `plugins/` directory
+- Dynamic instantiation with dependency injection
+- Hook registration for event interception
+- Configuration merging from plugin configs
+
+## Development Commands
+
+### Installation & Setup
+```bash
+# Install from source (development mode)
+pip install -e .
+
+# Install with development dependencies
+pip install -e ".[dev]"
+
+# Install from PyPI (for users)
+pip install kollabor
+```
+
+### Running the Application
+```bash
+# Using installed CLI command (after pip install)
+kollab
+
+# Using main.py directly (development)
+python main.py
+
+# Pipe mode examples
+kollab "What is Python?"
+echo "Explain async/await" | kollab -p
+cat document.txt | kollab -p --timeout 5min
+```
+
+### Testing
+```bash
+# Run all tests
+python tests/run_tests.py
+
+# Run specific test file
+python -m unittest tests.test_llm_plugin
+python -m unittest tests.test_config_manager
+python -m unittest tests.test_plugin_registry
+
+# Run individual test case
+python -m unittest tests.test_llm_plugin.TestLLMPlugin.test_thinking_tags_removal
+```
+
+### Code Quality
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Format code (Black is configured for 88-character line length)
+python -m black core/ plugins/ tests/ main.py
+
+# Type checking (if mypy is available)
+python -m mypy core/ plugins/
+
+# Run linting (if flake8 is available)
+python -m flake8 core/ plugins/ tests/ main.py --max-line-length=88
+
+# Clean up cache files and build artifacts
+python scripts/clean.py
+```
+
+### Building & Publishing
+```bash
+# Clean previous builds
+python scripts/clean.py
+
+# Build distribution packages
+python -m build
+
+# Upload to TestPyPI (for testing)
+python -m twine upload --repository testpypi dist/*
+
+# Upload to PyPI (production)
+python -m twine upload dist/*
+```
+
+### Debugging
+- Application logs to `.kollabor-cli/logs/kollabor.log` with daily rotation
+- Configuration stored in `.kollabor-cli/config.json`
+- State persistence in `.kollabor-cli/state.db`
+- Use `logging.getLogger(__name__)` in modules for consistent logging
+
+## Entry Points
+
+The application has two entry points:
+
+1. **`kollab` command** (after `pip install kollabor`):
+   - Entry point defined in `pyproject.toml` as `kollab = "kollabor_cli_main:cli_main"`
+   - Uses `kollabor_cli_main.py` → `core/cli.py` → `core/application.py`
+   - Preferred for end users and production use
+
+2. **`python main.py`** (development mode):
+   - Direct execution for development
+   - Imports from local `core/` directory
+   - Used during active development
+
+Both entry points initialize the `TerminalLLMChat` application orchestrator in `core/application.py`.
+
+## Configuration System
+
+Configuration uses dot notation (e.g., `config.get("core.llm.max_history", 90)`):
+- Core LLM settings: `core.llm.*`
+- Terminal rendering: `terminal.*`
+- Application metadata: `application.*`
+
+### Configuration Directories
+
+The application uses a **priority-based configuration directory system** (see `core/utils/config_utils.py`):
+
+**Resolution order:**
+1. **Local** `.kollabor-cli/` in current directory (project-specific override)
+2. **Global** `~/.kollabor-cli/` in home directory (default for most users)
+
+If local `.kollabor-cli/` exists, it takes precedence over global.
+
+**Directory contents:**
+- `config.json` - User configuration with plugin settings
+- `logs/` - Application logs with daily rotation
+- `state.db` - Persistent state and conversation history
+- `conversations/` - Conversation logs
+- `system_prompt/` - System prompt files (default.md, etc.)
+
+### System Prompt Initialization
+
+On first run (`initialize_system_prompt()` in `config_utils.py`):
+
+1. If **local** `.kollabor-cli/system_prompt/` exists with `.md` files → use local (project-specific)
+2. If global `~/.kollabor-cli/system_prompt/` doesn't exist → create from bundled `system_prompt/default.md`
+3. Copy all prompts from global to local for project-specific customization
+
+This ensures each project can have its own customized system prompts while maintaining a global default.
+
+## Core Architecture Patterns
+
+### Event-Driven Design
+The application uses an event bus (`core/events/bus.py`) that coordinates between:
+- **HookRegistry** (`core/events/registry.py`): Manages hook registration and lookup by event type
+- **HookExecutor** (`core/events/executor.py`): Handles hook execution with error handling and priority ordering
+- **EventProcessor** (`core/events/processor.py`): Processes events through registered hooks in sequence
+- **EventBus** (`core/events/bus.py`): Central coordinator that combines the above components
+
+### Plugin Lifecycle
+1. **Discovery**: `PluginDiscovery` scans `plugins/` directory for plugin modules
+2. **Registry**: `PluginRegistry` maintains loaded plugin metadata and configurations
+3. **Factory**: `PluginFactory` instantiates plugins with dependency injection (event_bus, config, renderer, state_manager)
+4. **Initialization**: Plugins call `initialize()` and `register_hooks()` during application startup
+5. **Execution**: Events trigger registered hooks through the event bus with priority ordering
+6. **Cleanup**: Plugins call `shutdown()` during application teardown
+
+### LLM Service Architecture
+The `LLMService` (`core/llm/llm_service.py`) orchestrates multiple specialized services:
+- **APICommunicationService**: HTTP client with rate limiting and retry logic
+- **KollaborConversationLogger**: Persistent conversation history to `.kollabor-cli/conversations/`
+- **MessageDisplayService**: Response formatting, streaming, and display coordination
+- **ToolExecutor**: Function calling execution and tool result processing
+- **MCPIntegration**: Model Context Protocol server discovery and integration
+- **KollaborPluginSDK**: Plugin development interface with helper methods
+- **LLMHookSystem**: LLM-specific hook management for request/response interception
+
+### Plugin System Details
+Plugins are discovered from two possible locations (in order):
+1. Package installation directory: `<package_root>/plugins/` (for pip install)
+2. Current working directory: `./plugins/` (for development mode)
+
+Each plugin can:
+- Register hooks at any priority level (CRITICAL, HIGH, NORMAL, LOW)
+- Access shared services via dependency injection
+- Contribute status line items to areas A, B, or C
+- Merge custom configuration into the global config
+- Register slash commands via the CommandRegistry
+
+## Hook System
+
+The application's hook system allows plugins to:
+- Intercept user input before processing (`pre_user_input`)
+- Transform LLM requests before API calls (`pre_api_request`)
+- Process responses before display (`post_api_response`)
+- Add custom status indicators via `get_status_line()`
+- Create new terminal UI elements
+
+## Plugin Development
+
+Plugins should:
+1. Inherit from base plugin classes in `core/plugins/`
+2. Register hooks in `register_hooks()` method using `EventType` enum
+3. Provide status line information via `get_status_line()`
+4. Implement `initialize()` and `shutdown()` lifecycle methods
+5. Follow the async/await pattern for all hook handlers
+
+## Project Structure
+
+```
+.
+├── core/                           # Core application modules
+│   ├── application.py             # Main orchestrator
+│   ├── config/                    # Configuration management
+│   ├── events/                    # Event bus and hook system
+│   ├── io/                        # Terminal I/O, rendering, input handling
+│   ├── llm/                       # LLM services (API, conversation, tools)
+│   ├── models/                    # Data models
+│   ├── plugins/                   # Plugin system (discovery, registry)
+│   ├── storage/                   # State management
+│   ├── utils/                     # Utility functions
+│   ├── commands/                  # Command system (parser, registry, executor)
+│   ├── ui/                        # UI system (modals, widgets, rendering)
+│   ├── effects/                   # Visual effects (matrix rain, etc.)
+│   └── logging/                   # Logging configuration
+├── plugins/                       # Plugin implementations
+│   ├── enhanced_input/           # Enhanced input plugin modules
+│   ├── enhanced_input_plugin.py  # Main enhanced input plugin
+│   ├── hook_monitoring_plugin.py # Hook system monitoring
+│   └── [other plugins]
+├── tests/                         # Test suite
+│   ├── run_tests.py              # Test runner
+│   ├── unit/                     # Unit tests
+│   ├── integration/              # Integration tests
+│   ├── visual/                   # Visual effect tests
+│   ├── test_*.py                 # Component tests
+│   └── README.md                 # Test documentation
+├── docs/                          # Comprehensive documentation
+│   ├── project-management/       # Project processes and templates
+│   ├── reference/                # API docs and architecture
+│   ├── sdlc/                     # Software development lifecycle
+│   ├── sop/                      # Standard operating procedures
+│   └── standards/                # Coding and quality standards
+├── main.py                       # Application entry point
+├── .kollabor-cli/                # Runtime data (created at startup)
+│   ├── config.json              # User configuration
+│   ├── logs/                    # Application logs
+│   └── state.db                 # Persistent state
+└── .github/scripts/              # Repository automation
+```
+
+Key directories:
+- **`core/`**: Modular core functionality with clear separation of concerns
+- **`plugins/`**: Dynamic plugin system with auto-discovery
+- **`tests/`**: Comprehensive test coverage with multiple test types
+- **`docs/`**: Extensive documentation following enterprise standards
+- **`.kollabor-cli/`**: Runtime configuration, logs, and state (created automatically)
+
+## Development Guidelines
+
+### Code Standards
+- Follow PEP 8 with 88-character line length (Black formatter)
+- Use double quotes for strings, single quotes for character literals
+- All async functions should use proper `async`/`await` patterns
+- Type hints required for all public functions and methods
+- Comprehensive docstrings for classes and public methods
+- Use `logging.getLogger(__name__)` for consistent logging across modules
+
+### Async/Await Patterns
+The application uses async/await throughout for responsive performance:
+- **Main event loop**: `asyncio.run()` in `cli_main()` starts the application
+- **Concurrent tasks**: Render loop and input handler run concurrently using `asyncio.gather()`
+- **Background tasks**: Use `app.create_background_task()` for proper task tracking and cleanup
+- **Cleanup**: All tasks cancelled in `app.cleanup()` with guaranteed execution via `finally` block
+- **Plugin hooks**: Must be async (`async def`) even if not using await internally
+
+### Testing Strategy
+- Unit tests in `tests/unit/` for individual components
+- Integration tests in `tests/integration/` for cross-component functionality
+- Visual tests in `tests/visual/` for terminal rendering
+- Component tests (`test_*.py`) for specific modules
+- Use unittest framework with descriptive test method names
+- Test coverage includes LLM plugins, configuration, and plugin registry
+
+### Hook Development
+When creating hooks, consider:
+- Hook priority using `HookPriority` enum (CRITICAL, HIGH, NORMAL, LOW)
+- Error handling - hooks should not crash the application (errors are caught by HookExecutor)
+- Performance - hooks are in the hot path for user interaction
+- State management - avoid shared mutable state between hooks
+- Return modified context from hooks (context is passed through hook chain)
+- All hook handlers must be async functions
+
+## Key Features
+
+### Interactive Mode
+Standard terminal-based chat interface with:
+- Real-time status updates across three status areas (A, B, C)
+- Thinking animations during LLM processing
+- Multi-line input with visual input box
+- Conversation history with scrollback
+- Plugin-driven extensibility
+
+### Pipe Mode
+Non-interactive mode for scripting and automation:
+- Process single query and exit: `kollab "query here"`
+- Read from stdin: `echo "query" | kollab -p`
+- Configurable timeout: `kollab --timeout 5min "complex task"`
+- Suppresses interactive UI elements (status bar, cursor, exit messages)
+- Full plugin support (plugins can check `app.pipe_mode` flag)
+- Automatically waits for LLM processing and tool calls to complete
+
+### Other Features
+- **Modal System**: Full-screen modal overlays with widget support (dropdowns, checkboxes, sliders, text inputs)
+- **Command System**: Extensible slash command parser and executor with menu rendering
+- **Plugin System**: Dynamic plugin discovery with comprehensive SDK
+- **Visual Effects**: Matrix rain effect and customizable color palettes
+- **Status Display**: Multi-area status rendering with flexible view registry
+- **Configuration**: Dot notation config system with plugin integration
+- **Message Processing**: Advanced response parsing with thinking tag removal
+
+## Current State
+
+Recent development focused on:
+- Enhanced input plugin architecture with modular design
+- LLM service output formatting consistency
+- Message display and error handling improvements
+- Event bus system with specialized components
+- Modal system with overlay rendering and widget integration
+- Command system with menu and executor components
+
+The codebase uses Python 3.12+ and follows async/await patterns throughout.

kollabor-0.4.9/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kollabor Contributors
+
+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.

kollabor-0.4.9/MANIFEST.in

@@ -0,0 +1,31 @@
+# Include documentation
+include README.md
+include LICENSE
+include CLAUDE.md
+include requirements.txt
+
+# Include all markdown files in docs
+recursive-include docs *.md
+recursive-include docs *.rst
+
+# Include plugin configuration files
+recursive-include plugins *.json
+recursive-include plugins *.yaml
+recursive-include plugins *.yml
+
+# Include type stubs
+recursive-include core *.pyi
+recursive-include plugins *.pyi
+
+# Exclude common unwanted files
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude *$py.class
+global-exclude *.so
+global-exclude .DS_Store
+global-exclude *.egg-info
+global-exclude .git*
+global-exclude .pytest_cache
+global-exclude .mypy_cache
+global-exclude .coverage
+global-exclude htmlcov