refactor: use any-llm to replace litellm

.github/workflows/main.yml

@@ -29,7 +29,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.11", "3.12", "3.13"]
       fail-fast: false
     defaults:
       run:

AGENT.md

@@ -0,0 +1,150 @@
+# AGENT.md - Bub Development Guide
+
+## Commands
+- **Test**: `uv run pytest --doctest-modules` or `make test`
+- **Test single**: `uv run pytest tests/test_specific.py::test_function`
+- **Test with coverage**: `uv run pytest --cov=src/bub`
+- **Lint/Check**: `make check` (runs pre-commit, mypy, lock check)
+- **Type check**: `uv run mypy` (targets `src/` only)
+- **Format**: `uv run ruff format .` and `uv run ruff check --fix .`
+- **Build**: `make build` (creates wheel with uvx pyproject-build)
+- **Docs**: `make docs` (serve) or `make docs-test` (build only)
+- **Install dev**: `make install` (uv sync + pre-commit install)
+- **Sync dependencies**: `uv sync`
+- **Add dependency**: `uv add package-name` or `uv add --dev package-name`
+- **Update lock**: `uv lock`
+
+## Python Style Guidelines (from .cursor/rules)
+
+### Naming Conventions
+- **Variables, functions, methods, packages, modules**: `snake_case_with_underscores`
+- **Classes and Exceptions**: `PascalCase`
+- **Protected methods**: `_single_leading_underscore`
+- **Private methods**: `__double_leading_underscore`
+- **Constants**: `ALL_CAPS_WITH_UNDERSCORES`
+
+### Code Style Best Practices
+- **Line length**: 120 chars max (ruff configured)
+- **Type hints**: Required for all functions and methods (mypy strict mode)
+- **Equality**: Use `is` for None/True/False, not `==`
+- **List comprehensions**: Preferred over for loops when possible
+- **File handling**: Always use `with` statement for file operations
+- **Comments**: Use sparingly, prefer self-documenting code
+
+### Imports Organization
+Organize imports in three sections, separated by blank lines:
+1. **System imports** (stdlib)
+2. **Third-party imports** (external packages)
+3. **Local imports** (project modules)
+
+```python
+import os
+from pathlib import Path
+
+import pydantic
+from typer import Typer
+
+from bub.events import EventManager
+from bub.hooks import BaseHook
+```
+
+### Documentation
+- **Docstrings**: Follow PEP 257 guidelines
+- **One-line docstrings**: For obvious functions
+- **Multi-line docstrings**: Include summary, args, return type
+- **Class docstrings**: Document `__init__` parameters in class docstring
+
+```python
+def process_event(event: BaseEvent) -> bool:
+    """Process an event and return success status."""
+    pass
+
+class EventProcessor:
+    """Processes events from the shell hook system.
+
+    Args:
+        config: Configuration object for the processor
+        logger: Optional logger instance
+    """
+    def __init__(self, config: Config, logger: Optional[Logger] = None):
+        pass
+```
+
+### Function Design
+- **Single responsibility**: Functions should do one thing
+- **2 or fewer parameters**: Use dataclasses/TypedDict for complex parameters
+- **Avoid flags**: Split functions instead of boolean parameters
+- **Descriptive names**: Function names should explain what they do
+- **One abstraction level**: Don't mix high and low-level operations
+
+### Testing Guidelines
+- **100% coverage goal**: Strive for complete test coverage
+- **Descriptive test names**: Test names should read like scenarios
+- **Isolated tests**: No external dependencies (real databases, networks)
+- **Use factories**: Prefer factory pattern over fixtures
+- **Fast tests**: Unit tests should be quick to run
+
+## UV Package Management
+
+### Project Setup
+```bash
+# Initialize new project
+uv init my-project
+
+# Add dependencies
+uv add requests 'flask>=2.0.0' 'pytest[testing]'
+
+# Add development dependencies
+uv add --dev black ruff mypy pytest-cov
+
+# Install all dependencies
+uv sync
+```
+
+### Virtual Environment
+- UV automatically manages `.venv` in project root
+- Activates automatically for `uv run` commands
+- Manual activation: `source .venv/bin/activate` (Unix) or `.venv\Scripts\activate` (Windows)
+
+### Dependency Management Best Practices
+- **Lock dependencies**: Always commit `uv.lock` file
+- **Semantic versioning**: Use `~=2.0.0` for compatible releases
+- **Version ranges**: Use `>=2.0.0,<3.0.0` for major version constraints
+- **Regular updates**: Run `uv lock --upgrade` periodically
+
+### CI/CD Integration
+```yaml
+# .github/workflows/ci.yml
+- name: Install UV
+  run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+- name: Setup Python
+  run: uv python install 3.12
+
+- name: Install dependencies
+  run: uv sync
+
+- name: Run tests
+  run: uv run pytest --cov=src/bub
+```
+
+## Version Control Best Practices
+- **Commit `uv.lock`**: Ensures reproducible builds
+- **Ignore `.venv/`**: Virtual environment shouldn't be versioned
+- **Ignore `__pycache__/`**: Python bytecode files
+- **Ignore `.pytest_cache/`**: Test cache directories
+
+## Development Workflow
+1. **Setup**: `make install` or `uv sync && pre-commit install`
+2. **Add feature**: Create feature branch
+3. **Code**: Follow style guidelines, add tests
+4. **Check**: Run `make check` before committing
+5. **Test**: Run `uv run pytest --cov=src/bub`
+6. **Commit**: Pre-commit hooks will run automatically
+7. **PR**: Submit pull request with tests and documentation
+
+## Performance Considerations
+- **Concurrent operations**: UV downloads packages in parallel
+- **Cache management**: UV caches wheels and metadata
+- **Build optimization**: Use prebuilt wheels when available
+- **Memory usage**: Monitor during large dependency installations

README.md

@@ -1,31 +1,122 @@
-# bub - Bub it. Build it.
+# Bub - Bub it. Build it.
 
-[![Release](https://img.shields.io/github/v/release/psiace/bub)](https://img.shields.io/github/v/release/psiace/bub)
+[![Release](https://img.shields.io/github/v/release/psiace/bub)](https://github.com/psiace/bub/releases)
 [![Build status](https://img.shields.io/github/actions/workflow/status/psiace/bub/main.yml?branch=main)](https://github.com/psiace/bub/actions/workflows/main.yml?query=branch%3Amain)
-[![Commit activity](https://img.shields.io/github/commit-activity/m/psiace/bub)](https://img.shields.io/github/commit-activity/m/psiace/bub)
-[![License](https://img.shields.io/github/license/psiace/bub)](https://img.shields.io/github/license/psiace/bub)
+[![Commit activity](https://img.shields.io/github/commit-activity/m/psiace/bub)](https://github.com/psiace/bub/graphs/commit-activity)
+[![License](https://img.shields.io/github/license/psiace/bub)](LICENSE)
 
-Bub is a CLI tool that helps you build things, with AI.
+Bub is an AI-powered CLI tool that helps you build, develop, and manage projects using natural language commands. With access to file operations, command execution, and intelligent reasoning, Bub acts as your coding assistant.
+
+## Installation
+
+```bash
+# Install from PyPI (when available)
+pip install bub
+
+# Or install from source
+git clone https://github.com/psiace/bub.git
+cd bub
+uv sync
+uv run bub --help
+```
 
 ## Quick Start
 
+### 1. Set up your API key
+
+Bub supports multiple AI providers through Any-LLM. Configure provider and model:
+
 ```bash
-# Set up your API key
-export BUB_API_KEY="your-api-key-here"
+# For OpenAI
+export BUB_PROVIDER="openai"
+export BUB_MODEL_NAME="gpt-4"
+export BUB_API_KEY="sk-..."
+
+# For Anthropic
+export BUB_PROVIDER="anthropic"
+export BUB_MODEL_NAME="claude-3-sonnet-20240229"
+export BUB_API_KEY="your-anthropic-key"
+
+# For local models with Ollama
+export BUB_PROVIDER="ollama"
+export BUB_MODEL_NAME="llama2"
+# No API key needed for local models
+```
+
+### 2. Start using Bub
 
-# Start interactive chat
+```bash
+# Interactive chat mode
 bub chat
 
 # Run a single command
-bub run "Create a hello world script"
+bub run "Create a Python script that prints 'Hello, World!'"
+
+# Specify workspace and model
+bub chat --workspace /path/to/project --model gpt-4
 
 # Get help
 bub --help
 ```
 
-- **Github repository**: <https://github.com/psiace/bub/>
-- **Documentation** <https://bub.build/>
+## Usage Examples
+
+```bash
+# Create files
+bub run "Create a README.md for a Python project"
+
+# Code assistance
+bub run "Add error handling to my main.py file"
+
+# Project setup
+bub run "Initialize a new FastAPI project with basic structure"
+
+# Code review
+bub run "Review my code and suggest improvements"
+```
+
+## Configuration
+
+Bub can be configured via environment variables or a `.env` file:
+
+```bash
+BUB_API_KEY=your-api-key-here
+BUB_MODEL=gpt-4                    # AI model to use
+BUB_API_BASE=https://api.custom.ai # Custom API endpoint
+BUB_MAX_TOKENS=4000               # Maximum response tokens
+BUB_WORKSPACE_PATH=/path/to/work  # Default workspace
+```
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/psiace/bub.git
+cd bub
+
+# Install dependencies
+uv sync
+
+# Run tests
+make test
+
+# Run linting and type checking
+make check
+
+# Build documentation
+make docs
+```
+
+## Contributing
+
+Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Links
+
+- **GitHub Repository**: https://github.com/psiace/bub/
+- **Documentation**: https://bub.build/
+- **PyPI Package**: https://pypi.org/project/bub/
 
----
+## License
 
-Repository initiated with [fpgmaas/cookiecutter-uv](https://github.com/fpgmaas/cookiecutter-uv).
+This project is licensed under the Apache-2.0 License - see the [LICENSE](LICENSE) file for details.