kollabor 0.1.0__tar.gz

kollabor-0.1.0/CLAUDE.md

@@ -0,0 +1,243 @@
+# 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
+
+### Running the Application
+```bash
+python main.py
+```
+
+### 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
+```
+
+### Debugging
+- Application logs to `.kollabor/logs/kollabor.log` with daily rotation
+- Configuration stored in `.kollabor/config.json`
+- State persistence in `.kollabor/state.db`
+
+## 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.*`
+
+## Core Architecture Patterns
+
+### Event-Driven Design
+The application uses an event bus (`core/events/bus.py`) that coordinates between:
+- **HookRegistry**: Manages hook registration and lookup
+- **HookExecutor**: Handles hook execution with error handling
+- **EventProcessor**: Processes events through registered hooks
+
+### Plugin Lifecycle
+1. **Discovery**: `PluginDiscovery` scans `plugins/` directory
+2. **Factory**: `PluginFactory` instantiates plugins with dependency injection
+3. **Registration**: Plugins register hooks during initialization
+4. **Execution**: Events trigger hooks through the event bus
+
+### LLM Service Architecture
+The `LLMService` (`core/llm/llm_service.py`) orchestrates:
+- **APICommunicationService**: HTTP client with rate limiting
+- **KollaborConversationLogger**: Persistent conversation history
+- **MessageDisplayService**: Response formatting and display
+- **ToolExecutor**: Function calling execution
+- **MCPIntegration**: Model Context Protocol support
+- **KollaborPluginSDK**: Plugin development interface
+- **LLMHookSystem**: LLM-specific hook management
+
+## 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/                    # 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/`**: 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
+
+### 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
+- Performance - hooks are in the hot path for user interaction
+- State management - avoid shared mutable state between hooks
+
+## Key Features
+
+Current implementation includes:
+- **Modal System**: Full-screen modal overlays with widget support (dropdowns, checkboxes, sliders, text inputs)
+- **Command System**: Extensible 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.1.0/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.1.0/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

kollabor-0.1.0/PKG-INFO

@@ -0,0 +1,247 @@
+Metadata-Version: 2.4
+Name: kollabor
+Version: 0.1.0
+Summary: An advanced, highly customizable terminal-based chat application for interacting with LLMs
+Author-email: Kollabor Contributors <contributors@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/malmazan/kollabor-cli
+Project-URL: Repository, https://github.com/malmazan/kollabor-cli
+Project-URL: Documentation, https://github.com/malmazan/kollabor-cli/blob/main/docs/
+Project-URL: Bug Tracker, https://github.com/malmazan/kollabor-cli/issues
+Keywords: llm,cli,chat,terminal,ai,chatbot,assistant,kollabor,plugin-system,event-driven
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Terminals
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.10.11
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Dynamic: license-file
+
+# Kollabor
+
+[![Python Version](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+An advanced, highly customizable terminal-based chat application for interacting with Large Language Models (LLMs). Built with a powerful plugin system and comprehensive hook architecture for complete customization.
+
+**Install:** `pip install kollabor`
+**Run:** `kollab`
+
+## Features
+
+- **Event-Driven Architecture**: Everything has hooks - every action triggers customizable hooks that plugins can attach to
+- **Advanced Plugin System**: Dynamic plugin discovery and loading with comprehensive SDK
+- **Rich Terminal UI**: Beautiful terminal rendering with status areas, visual effects, and modal overlays
+- **Conversation Management**: Persistent conversation history with full logging support
+- **Model Context Protocol (MCP)**: Built-in support for MCP integration
+- **Tool Execution**: Function calling and tool execution capabilities
+- **Pipe Mode**: Non-interactive mode for scripting and automation
+- **Extensible Configuration**: Flexible configuration system with plugin integration
+- **Async/Await Throughout**: Modern Python async patterns for responsive performance
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install kollabor
+```
+
+### From Source
+
+```bash
+git clone https://github.com/malmazan/kollabor-cli.git
+cd kollabor-cli
+pip install -e .
+```
+
+### Development Installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### Interactive Mode
+
+Simply run the CLI to start an interactive chat session:
+
+```bash
+kollab
+```
+
+### Pipe Mode
+
+Process a single query and exit:
+
+```bash
+# Direct query
+kollab "What is the capital of France?"
+
+# From stdin
+echo "Explain quantum computing" | kollab -p
+
+# From file
+cat document.txt | kollab -p
+
+# With custom timeout
+kollab --timeout 5min "Complex analysis task"
+```
+
+## Configuration
+
+On first run, Kollabor creates a `.kollabor` directory in your current working directory:
+
+```
+.kollabor/
+├── config.json    # User configuration
+├── logs/          # Application logs
+└── state.db       # Persistent state
+```
+
+### Configuration Options
+
+The configuration system uses dot notation:
+
+- `core.llm.*` - LLM service settings
+- `terminal.*` - Terminal rendering options
+- `application.*` - Application metadata
+
+## Architecture
+
+Kollabor follows a modular, event-driven architecture:
+
+### Core Components
+
+- **Application Core** (`core/application.py`): Main orchestrator
+- **Event System** (`core/events/`): Central event bus with hook system
+- **LLM Services** (`core/llm/`): API communication, conversation management, tool execution
+- **I/O System** (`core/io/`): Terminal rendering, input handling, visual effects
+- **Plugin System** (`core/plugins/`): Dynamic plugin discovery and loading
+- **Configuration** (`core/config/`): Flexible configuration management
+- **Storage** (`core/storage/`): State management and persistence
+
+### Plugin Development
+
+Create custom plugins by inheriting from base plugin classes:
+
+```python
+from core.plugins import BasePlugin
+from core.events import EventType
+
+class MyPlugin(BasePlugin):
+    def register_hooks(self):
+        """Register plugin hooks."""
+        self.event_bus.register_hook(
+            EventType.PRE_USER_INPUT,
+            self.on_user_input,
+            priority=HookPriority.NORMAL
+        )
+
+    async def on_user_input(self, context):
+        """Process user input before it's sent to the LLM."""
+        # Your custom logic here
+        return context
+
+    def get_status_line(self):
+        """Provide status information for the status bar."""
+        return "MyPlugin: Active"
+```
+
+## Hook System
+
+The comprehensive hook system allows plugins to intercept and modify behavior at every stage:
+
+- `pre_user_input` - Before processing user input
+- `pre_api_request` - Before API calls to LLM
+- `post_api_response` - After receiving LLM responses
+- `pre_message_display` - Before displaying messages
+- `post_message_display` - After displaying messages
+- And many more...
+
+## Project Structure
+
+```
+kollabor/
+├── core/              # Core application modules
+│   ├── application.py # Main orchestrator
+│   ├── config/        # Configuration management
+│   ├── events/        # Event bus and hooks
+│   ├── io/            # Terminal I/O
+│   ├── llm/           # LLM services
+│   ├── plugins/       # Plugin system
+│   └── storage/       # State management
+├── plugins/           # Plugin implementations
+├── docs/              # Documentation
+├── tests/             # Test suite
+└── main.py            # Application entry point
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# All tests
+python tests/run_tests.py
+
+# Specific test file
+python -m unittest tests.test_llm_plugin
+
+# Individual test case
+python -m unittest tests.test_llm_plugin.TestLLMPlugin.test_thinking_tags_removal
+```
+
+### Code Quality
+
+```bash
+# Format code
+python -m black core/ plugins/ tests/ main.py
+
+# Type checking
+python -m mypy core/ plugins/
+
+# Linting
+python -m flake8 core/ plugins/ tests/ main.py --max-line-length=88
+
+# Clean up cache files and build artifacts
+python scripts/clean.py
+```
+
+## Requirements
+
+- Python 3.12 or higher
+- aiohttp 3.8.0 or higher
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Contributing
+
+Contributions are welcome! Please see the documentation for development guidelines.
+
+## Links
+
+- [Documentation](https://github.com/malmazan/kollabor-cli/blob/main/docs/)
+- [Bug Tracker](https://github.com/malmazan/kollabor-cli/issues)
+- [Repository](https://github.com/malmazan/kollabor-cli)
+
+## Acknowledgments
+
+Built with modern Python async/await patterns and designed for extensibility and customization.