kader 0.1.0__tar.gz

kader-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run ruff check
+        run: uv run ruff check .
+
+      - name: Run ruff format check
+        run: uv run ruff format --check .
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run tests
+        run: |
+          uv run pytest tests/ -v \
+            --deselect tests/tools/test_filesystem_tools.py::TestSearchInDirectoryTool::test_execute_search \
+            --deselect tests/tools/test_filesystem_tools.py::TestSearchInDirectoryTool::test_async_execute

kader-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,34 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-publish:
+    name: Build and Publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}

kader-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.pytest_cache/
+.ruff_cache/
+
+# Virtual environments
+.venv
+
+# IDE
+.idea
+.vscode
+
+# secret files
+.env
+
+# optimization
+optimizers/

kader-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

kader-0.1.0/.qwen/QWEN.md

@@ -0,0 +1,10 @@
+## General Instructions
+
+- Current Operating System is Windows, Use cmd to run terminal commands.
+- use uv as python dependency manager.
+- check `pyproject.toml` file to search for dependencies first before add dependencies.
+- use context7 mcp tools to search to get accurate docs if needed.
+- to install new packages/dependecies use `uv add <package-name>`.
+- to remove packages/dependecies use `uv remove <package-name>`.
+- use `uv run <script-name>` to run python scripts.
+- don't access secrets like api keys, tokens, etc. from environment variables, or files like `.env`.

kader-0.1.0/.qwen/agents/technical-writer.md

@@ -0,0 +1,49 @@
+---
+name: technical-writer
+description: Use this agent when creating user guides, README files, architecture documentation, code comments, or any technical documentation that needs to be clear, accessible, and user-focused. This agent specializes in writing documentation that helps users accomplish specific outcomes with step-by-step instructions, real examples, and troubleshooting guidance.
+color: Cyan
+---
+
+You are an expert technical writer specializing in creating clear, accessible, and user-focused documentation. Your primary goal is to help users successfully accomplish their objectives through well-structured, comprehensive documentation.
+
+## Core Responsibilities
+- Create user guides and tutorials with step-by-step instructions
+- Write README files and getting started documentation
+- Develop architecture and design documentation
+- Craft code comments and inline documentation
+- Ensure content accessibility using plain language principles
+- Organize information with effective information architecture
+
+## Documentation Approach
+1. Always write for your specific audience - assess and acknowledge their skill level upfront
+2. Lead with the outcome - clearly state what users will accomplish
+3. Use active voice and clear, concise language
+4. Include real examples and practical scenarios
+5. Test instructions by following them exactly as written
+6. Structure content with clear headings and logical flow
+7. Include troubleshooting sections and highlight common pitfalls
+
+## Content Creation Standards
+- Write comprehensive user guides with clear navigation
+- Create README templates with appropriate badges and well-organized sections
+- Develop tutorial series with progressive complexity
+- Document architecture decision records (ADRs) with clear rationale
+- Establish code documentation standards
+- Maintain a content style guide with consistent writing conventions
+
+## Quality Assurance
+- Verify all technical accuracy of instructions
+- Ensure examples are complete and functional
+- Include error handling and troubleshooting guidance
+- Anticipate user questions and address them proactively
+- Review content for accessibility and plain language compliance
+
+## Output Requirements
+- Provide structured documentation with appropriate headings
+- Include practical examples with expected outputs
+- Add troubleshooting sections for common issues
+- Use consistent formatting and style
+- Ensure content is scannable and easy to navigate
+- Include links to related resources when appropriate
+
+Focus on user success above all else. Your documentation should enable users to achieve their goals efficiently and confidently.

kader-0.1.0/.qwen/agents/test-automation-specialist.md

@@ -0,0 +1,66 @@
+---
+name: test-automation-specialist
+description: Use this agent when you need comprehensive test automation strategy and implementation including unit, integration, and E2E tests with proper mocking, fixtures, and CI/CD pipeline configuration. This agent specializes in creating robust, fast, and deterministic test suites following the test pyramid approach.
+color: Red
+---
+
+You are an elite test automation specialist with deep expertise in comprehensive testing strategies across the full testing spectrum. Your primary responsibility is to design and implement robust, efficient, and maintainable test suites that follow industry best practices and ensure high software quality.
+
+## Core Responsibilities
+- Design unit tests with appropriate mocking and fixtures
+- Create integration tests using test containers
+- Implement E2E tests with Playwright or Cypress
+- Configure CI/CD test pipelines
+- Manage test data with factories and fixtures
+- Set up coverage analysis and reporting
+
+## Testing Approach
+1. Follow the test pyramid principle: many unit tests, fewer integration tests, minimal E2E tests
+2. Apply the Arrange-Act-Assert pattern consistently
+3. Write behavior-focused tests rather than implementation-focused tests
+4. Ensure all tests are deterministic with no flakiness
+5. Optimize for fast feedback through parallelization when possible
+
+## Framework Selection
+- Use Jest for JavaScript/Node.js projects
+- Use pytest for Python projects
+- Use appropriate frameworks for other languages (e.g., JUnit for Java, NUnit for .NET)
+- Select Playwright or Cypress based on project requirements for E2E testing
+
+## Output Requirements
+1. Create test suites with clear, descriptive test names that explain the expected behavior
+2. Provide mock/stub implementations for external dependencies
+3. Design test data factories or fixtures for consistent test data management
+4. Generate CI pipeline configuration for running tests
+5. Set up coverage reporting with appropriate thresholds
+6. Define E2E test scenarios for critical user paths
+
+## Quality Standards
+- Include both happy path and edge case scenarios in all test types
+- Ensure tests are isolated and can run independently
+- Maintain fast execution times by optimizing test setup and teardown
+- Write self-documenting tests that clearly express intent
+- Follow the principle of testing behavior rather than implementation details
+
+## Methodology
+1. Analyze the codebase or feature requirements to determine appropriate test coverage
+2. Design unit tests focusing on individual functions and components
+3. Create integration tests for interactions between components or services
+4. Develop E2E tests for critical user journeys and business flows
+5. Set up proper test data management using factories or fixtures
+6. Configure CI/CD pipeline with appropriate test execution order
+7. Establish coverage reporting with quality gates
+
+## Error Handling
+- Identify potential failure points and create appropriate negative test cases
+- Handle asynchronous operations properly in tests
+- Address race conditions and timing issues in integration tests
+- Ensure proper cleanup of test resources and data
+
+## Performance Optimization
+- Implement parallel test execution where appropriate
+- Use efficient test data setup and teardown
+- Optimize test execution order to provide fast feedback on critical functionality
+- Minimize external dependencies in unit tests through effective mocking
+
+Your output should include all necessary code, configuration files, and documentation to implement a complete testing strategy that follows these principles.

kader-0.1.0/PKG-INFO

@@ -0,0 +1,319 @@
+Metadata-Version: 2.4
+Name: kader
+Version: 0.1.0
+Summary: kader coding agent
+Requires-Python: >=3.11
+Requires-Dist: faiss-cpu>=1.9.0
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: ollama>=0.6.1
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: tenacity>=9.1.2
+Requires-Dist: textual[syntax]>=6.8.0
+Requires-Dist: typing-extensions>=4.15.0
+Requires-Dist: wcmatch>=10.1
+Description-Content-Type: text/markdown
+
+# Kader
+
+Kader is an intelligent coding agent designed to assist with software development tasks. It provides a comprehensive framework for building AI-powered agents with advanced reasoning capabilities and tool integration.
+
+## Features
+
+- 🤖 **AI-powered Code Assistance** - Using Ollama for local LLM execution
+- 🖥️ **Interactive CLI** - Modern TUI interface built with Textual
+- 🛠️ **Tool Integration** - File system, command execution, web search, and more
+- 🧠 **Memory Management** - State persistence and conversation history
+- 🔁 **Session Management** - Save and load conversation sessions
+- 🎨 **Theming** - Multiple color themes for the CLI interface
+- ⌨️ **Keyboard Shortcuts** - Efficient navigation and operations
+- 📝 **YAML Configuration** - Agent configuration via YAML files
+- 🔄 **ReAct Agent Framework** - Reasoning and Acting agent architecture
+- 🗂️ **File System Tools** - Read, write, search, and edit files
+- 🔍 **Planning Agent** - Task planning and execution capabilities
+
+## Installation
+
+### Prerequisites
+
+- Python 3.11 or higher
+- [Ollama](https://ollama.ai/) running locally to use LLMs
+- [uv](https://docs.astral.sh/uv/) package manager (recommended) or [pip](https://pypi.org/project/pip/)
+
+### Using uv (recommended)
+
+```bash
+# Clone the repository
+git clone https://github.com/your-repo/kader.git
+cd kader
+
+# Install dependencies with uv
+uv sync
+
+# Run the CLI
+uv run python -m cli
+```
+
+### Using pip
+
+```bash
+# Clone the repository
+git clone https://github.com/your-repo/kader.git
+cd kader
+
+# Install in development mode
+pip install -e .
+
+# Run the CLI
+python -m cli
+```
+
+## Quick Start
+
+### Running the CLI
+
+```bash
+# Run the Kader CLI using uv
+uv run python -m cli
+
+# Or using pip
+python -m cli
+```
+
+### First Steps in CLI
+
+Once the CLI is running:
+
+1. Type any question to start chatting with the agent
+2. Use `/help` to see available commands
+3. Use `/models` to check available models
+4. Use `/theme` to cycle through color themes
+
+## Configuration
+
+When the kader module is imported for the first time, it automatically:
+1. Creates a `.kader` directory in your home directory (`~/.kader` on Unix systems, `%USERPROFILE%\.kader` on Windows)
+2. Creates a `.env` file with the required configuration (including `OLLAMA_API_KEY=''`)
+3. Loads all environment variables from the `.env` file into the application environment
+
+### Environment Variables
+
+The application automatically loads environment variables from `~/.kader/.env`:
+- `OLLAMA_API_KEY`: API key for Ollama service (default: empty)
+- Additional variables can be added to the `.env` file and will be automatically loaded
+
+### Memory and Sessions
+
+Kader stores data in `~/.kader/`:
+- Sessions: `~/.kader/sessions/`
+- Configuration: `~/.kader/`
+- Memory files: `~/.kader/memory/`
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show command reference |
+| `/models` | Show available Ollama models |
+| `/theme` | Cycle color themes |
+| `/clear` | Clear conversation |
+| `/save` | Save current session |
+| `/load <id>` | Load a saved session |
+| `/sessions` | List saved sessions |
+| `/refresh` | Refresh file tree |
+| `/exit` | Exit the CLI |
+
+### Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl+Q` | Quit |
+| `Ctrl+L` | Clear conversation |
+| `Ctrl+T` | Cycle theme |
+| `Ctrl+S` | Save session |
+| `Ctrl+R` | Refresh file tree |
+| `Tab` | Navigate panels |
+
+## Project Structure
+
+```
+kader/
+├── cli/                    # Interactive command-line interface
+│   ├── app.py             # Main application entry point
+│   ├── app.tcss           # Textual CSS for styling
+│   ├── utils.py           # Utility functions and constants
+│   ├── widgets/           # Custom Textual widgets
+│   │   ├── conversation.py # Chat display widget
+│   │   ├── loading.py     # Loading spinner widget
+│   │   └── confirmation.py # Tool/model selection widgets
+│   └── README.md          # CLI documentation
+├── examples/              # Example implementations
+│   ├── memory_example.py  # Memory management examples
+│   ├── ollama_example.py  # Ollama provider examples
+│   ├── react_agent_example.py # ReAct agent examples
+│   ├── planning_agent_example.py # Planning agent examples
+│   ├── python_developer/  # Python expert agent example
+│   ├── todo_agent/       # Todo management agent example
+│   └── README.md         # Examples documentation
+├── kader/                # Core framework
+│   ├── agent/            # Agent implementations
+│   ├── memory/           # Memory management
+│   ├── providers/        # LLM providers
+│   ├── tools/            # Tools and utilities
+│   └── prompts/          # Prompt templates
+├── pyproject.toml        # Project dependencies
+├── README.md             # This file
+└── uv.lock               # Dependency lock file
+```
+
+## Core Components
+
+### Agents
+
+Kader provides several agent types:
+
+- **ReActAgent**: Reasoning and Acting agent that combines thoughts with actions
+- **PlanningAgent**: Agent that plans multi-step tasks
+- **BaseAgent**: Base agent class for creating custom agents
+
+### Memory Management
+
+Kader's memory system includes:
+
+- **AgentState**: Persistent key-value storage for agents
+- **RequestState**: Ephemeral request-scoped state
+- **FileSessionManager**: Session persistence to disk
+- **SlidingWindowConversationManager**: Conversation windowing
+
+### Tools
+
+Kader includes a rich set of tools:
+
+- **File System Tools**: Read, write, edit, search files
+- **Command Executor**: Execute shell commands safely
+- **Web Tools**: Search and fetch web content
+- **RAG Tools**: Retrieval Augmented Generation capabilities
+
+## Examples
+
+Check out the examples directory for comprehensive demonstrations of Kader's features:
+
+### Basic Examples
+
+- `memory_example.py`: Shows memory management capabilities
+- `ollama_example.py`: Demonstrates how to use the Ollama provider for LLM interactions
+- `tools_example.py`: Demonstrates the various tools available in Kader
+- `simple_agent.py`: Basic agent implementation example
+
+### Advanced Examples
+
+- `react_agent_example.py`: Interactive ReAct agent with tool integration
+- `planning_agent_example.py`: Planning agent for multi-step tasks
+- `python_developer/`: Specialized Python expert agent (YAML-configured)
+- `todo_agent/`: Task management agent with TodoTool
+
+### Running Examples
+
+Use uv to run examples:
+
+```bash
+uv run python -m examples.memory_example
+uv run python -m examples.ollama_example
+uv run python -m examples.tools_example
+uv run python -m examples.react_agent_example
+uv run python -m examples.python_developer.main
+uv run python -m examples.todo_agent.main
+```
+
+## Architecture
+
+### Agent Architecture
+
+Kader uses a modular architecture where:
+
+1. **Agents** define the behavior and reasoning strategy
+2. **Tools** provide capabilities for external interactions
+3. **Memory** manages state and conversation history
+4. **Providers** handle LLM interactions
+
+### Tool Architecture
+
+Tools in Kader follow a standardized interface:
+
+- Each tool has a schema defining its inputs and outputs
+- Tools can be registered in a ToolRegistry
+- Tools can be executed synchronously or asynchronously
+- Tools can be configured with parameters
+
+## Development
+
+### Setting up for Development
+
+```bash
+# Clone the repository
+git clone https://github.com/your-repo/kader.git
+cd kader
+
+# Install in development mode with uv
+uv sync
+
+# Run the CLI with hot reload for development
+uv run textual run --dev cli.app:KaderApp
+```
+
+### Running Tests
+
+```bash
+# Run tests with uv
+uv run pytest
+
+# Run tests with specific options
+uv run pytest --verbose
+```
+
+### Code Quality
+
+Kader uses various tools for maintaining code quality:
+
+```bash
+# Run linter
+uv run ruff check .
+
+# Format code
+uv run ruff format .
+```
+
+## Troubleshooting
+
+### Common Issues
+
+- **No models found**: Make sure Ollama is running and you have at least one model installed (e.g., `ollama pull gpt-oss:120b-cloud`)
+- **Connection errors**: Verify that Ollama service is accessible at the configured endpoint
+- **Theme not changing**: Some terminal emulators may not support all color themes
+
+### Debugging
+
+If you encounter issues:
+
+1. Check that Ollama is running: `ollama serve`
+2. Verify your model is pulled: `ollama list`
+3. Ensure your terminal supports the required features
+4. Check the logs for specific error messages
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Run the test suite
+6. Submit a pull request
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Acknowledgments
+
+- Built with [Textual](https://textual.textualize.io/) for the beautiful CLI interface
+- Uses [Ollama](https://ollama.ai/) for local LLM execution
+- Inspired by ReAct (Reasoning and Acting) agent architecture