feat: Add comprehensive test suite and tools implementation

- Add test suite with high coverage for tools\n- Implement weather tool with caching and error handling\n- Add health check system with resource monitoring\n- Implement circuit breaker for API resilience\n- Add timezone conversion utilities\n- Add usage statistics collection\n- Add system monitoring capabilities\n- Add cache management with TTL support\n- Add comprehensive documentation\n- Add development tooling and configuration

.flake8

@@ -0,0 +1,65 @@
+[flake8]
+max-line-length = 100
+max-complexity = 10
+extend-ignore = 
+    E203,  # Whitespace before ':'
+    W503,  # Line break before binary operator
+    D100,  # Missing docstring in public module
+    D104,  # Missing docstring in public package
+    D107,  # Missing docstring in __init__
+    B008   # Do not perform function calls in argument defaults
+extend-select = 
+    B950,  # Line too long
+    B901,  # Return statements in finally blocks
+    B902,  # Invalid first argument names for methods
+    B903   # __slots__ efficiency
+
+exclude = 
+    .git,
+    __pycache__,
+    build,
+    dist,
+    *.egg-info,
+    venv,
+    .env,
+    .venv,
+    .mypy_cache,
+    .pytest_cache
+
+per-file-ignores =
+    __init__.py: F401,F403
+    tests/*: S101,D103,ANN
+    conftest.py: D103
+
+# Plugin settings
+docstring-convention = google
+ignore-decorators = property|classmethod|staticmethod|validator|root_validator
+
+# Complexity settings
+max-annotations-complexity = 4
+max-expression-complexity = 7
+max-cognitive-complexity = 12
+
+# Additional settings
+max-line-doc-length = 100
+max-doc-length = 100
+statistics = True
+count = True
+show-source = True
+
+# Error format
+format = %(path)s:%(row)d:%(col)d: %(code)s %(text)s
+
+# Plugin configurations
+[flake8:local-plugins]
+extension =
+    B = flake8_bugbear:BugBearChecker
+    C = flake8_comprehensions:ComprehensionChecker
+    ANN = flake8_annotations:AnnotationChecker
+    CCR = flake8_cognitive_complexity:CognitiveComplexityChecker
+    ECE = flake8_expression_complexity:ExpressionComplexityChecker
+    DAR = flake8_darglint:DarglintChecker
+
+# Darglint configuration
+strictness = short
+docstring_style = google 

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,42 @@
+---
+name: Bug Report
+about: Create a report to help us improve
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Bug Description
+<!-- A clear and concise description of what the bug is -->
+
+## Steps to Reproduce
+1. 
+2. 
+3. 
+
+## Expected Behavior
+<!-- A clear and concise description of what you expected to happen -->
+
+## Actual Behavior
+<!-- What actually happened -->
+
+## Screenshots/Logs
+<!-- If applicable, add screenshots or logs to help explain your problem -->
+
+## Environment
+- OS: [e.g., Ubuntu 22.04, Windows 11]
+- Python Version: [e.g., 3.9.12]
+- Package Version: [e.g., 0.1.0]
+- Dependencies Versions:
+  ```
+  Output of: pip freeze | grep -i ai-assistant
+  ```
+
+## Additional Context
+<!-- Add any other context about the problem here -->
+
+## Possible Solution
+<!-- Optional: suggest a fix or reason for the bug -->
+
+## Related Issues/PRs
+<!-- Optional: link to related issues or PRs --> 

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,14 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question or Discussion
+    url: https://github.com/yourusername/ai-assistant/discussions
+    about: Ask questions and discuss with other community members
+  - name: Documentation
+    url: https://yourusername.github.io/ai-assistant
+    about: Check out our documentation for answers
+  - name: Security Issue
+    url: https://github.com/yourusername/ai-assistant/security/policy
+    about: Please report security vulnerabilities here
+
+# Configure issue template chooser
+# https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#configuring-the-template-chooser 

.github/ISSUE_TEMPLATE/documentation.md

@@ -0,0 +1,36 @@
+---
+name: Documentation
+about: Report an issue or suggest an improvement in documentation
+title: '[DOCS] '
+labels: documentation
+assignees: ''
+---
+
+## Documentation Location
+<!-- Specify where the documentation issue is (e.g., README, API docs, code comments) -->
+
+## Current Documentation
+<!-- What does the current documentation say? -->
+
+## Issue/Suggested Improvement
+<!-- Describe what's wrong or what could be better -->
+
+## Proposed Changes
+<!-- Suggest specific changes or improvements -->
+
+### Example
+<!-- If applicable, provide an example of the improved documentation -->
+```markdown
+# Suggested documentation changes
+```
+
+## Additional Context
+<!-- Add any other context about the documentation issue here -->
+
+## Checklist
+- [ ] I have checked that this is not already documented elsewhere
+- [ ] I have checked the latest documentation in the main branch
+- [ ] I have checked related issues/PRs
+
+## Related Issues/PRs
+<!-- Optional: link to related issues or PRs --> 

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,42 @@
+---
+name: Feature Request
+about: Suggest an idea for this project
+title: '[FEATURE] '
+labels: enhancement
+assignees: ''
+---
+
+## Problem Statement
+<!-- A clear and concise description of what problem this feature would solve -->
+
+## Proposed Solution
+<!-- A clear and concise description of what you want to happen -->
+
+## Alternative Solutions
+<!-- A clear and concise description of any alternative solutions or features you've considered -->
+
+## Example Use Case
+<!-- Provide an example of how this feature would be used -->
+```python
+# Example code showing how the feature might work
+from ai_assistant import SomeFeature
+
+# Usage example
+```
+
+## Implementation Details
+<!-- Optional: If you have ideas about how to implement this feature -->
+
+### Required Changes
+<!-- List the components that would need to be modified -->
+- [ ] Component 1
+- [ ] Component 2
+
+### Potential Challenges
+<!-- List any challenges or considerations for implementing this feature -->
+
+## Additional Context
+<!-- Add any other context or screenshots about the feature request here -->
+
+## Related Issues/PRs
+<!-- Optional: link to related issues or PRs --> 

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,62 @@
+## Description
+<!-- Provide a brief description of the changes in this PR -->
+
+## Type of Change
+<!-- Mark the appropriate option with an [x] -->
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+- [ ] Performance improvement
+- [ ] Code cleanup or refactor
+- [ ] Dependency update
+- [ ] Other (please describe):
+
+## Motivation and Context
+<!-- Why is this change required? What problem does it solve? -->
+
+## Implementation Details
+<!-- Describe the changes in detail -->
+
+## How Has This Been Tested?
+<!-- Describe the tests you ran and how -->
+- [ ] Unit tests added/updated
+- [ ] Integration tests added/updated
+- [ ] Manual testing performed
+
+### Test Configuration
+- Python version:
+- OS:
+- Dependencies:
+
+## Breaking Changes
+<!-- List any breaking changes and migration instructions if applicable -->
+
+## Checklist
+<!-- Mark completed items with an [x] -->
+- [ ] My code follows the project's style guidelines
+- [ ] I have performed a self-review of my own code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have made corresponding changes to the documentation
+- [ ] My changes generate no new warnings
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] New and existing unit tests pass locally with my changes
+- [ ] Any dependent changes have been merged and published
+- [ ] I have updated the version number if necessary
+- [ ] I have updated the changelog if necessary
+
+## Screenshots/Recordings
+<!-- If applicable, add screenshots or recordings to demonstrate the changes -->
+
+## Related Issues
+<!-- Link to any related issues using #issue-number -->
+Closes #
+
+## Additional Notes
+<!-- Add any additional notes or context about the PR here -->
+
+## Review Guidelines
+<!-- Specify any particular areas of the code that need careful review -->
+
+## Deployment Notes
+<!-- Any special considerations for deploying these changes --> 

.github/workflows/deploy.yml

@@ -0,0 +1,145 @@
+name: Deploy
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: 'Environment to deploy to'
+        required: true
+        default: 'staging'
+        type: choice
+        options:
+          - staging
+          - production
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.12"
+        cache: 'pip'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+
+    - name: Build package
+      run: |
+        python -m build
+
+    - name: Upload dist artifact
+      uses: actions/upload-artifact@v3
+      with:
+        name: dist
+        path: dist/
+        if-no-files-found: error
+
+  test-package:
+    needs: build
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: 'pip'
+
+    - name: Download dist
+      uses: actions/download-artifact@v3
+      with:
+        name: dist
+        path: dist/
+
+    - name: Install package
+      run: |
+        python -m pip install --upgrade pip
+        pip install dist/*.whl
+
+    - name: Test import
+      run: |
+        python -c "import tools; print(tools.__version__)"
+
+  deploy-staging:
+    needs: [build, test-package]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch' && github.event.inputs.environment == 'staging'
+    environment:
+      name: staging
+      url: ${{ steps.deploy.outputs.url }}
+    
+    steps:
+    - name: Download dist
+      uses: actions/download-artifact@v3
+      with:
+        name: dist
+        path: dist/
+
+    - name: Deploy to Test PyPI
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.TEST_PYPI_TOKEN }}
+      run: |
+        python -m twine upload --repository testpypi dist/*
+
+    - name: Set output URL
+      id: deploy
+      run: echo "url=https://test.pypi.org/project/ai-assistant/" >> $GITHUB_OUTPUT
+
+  deploy-production:
+    needs: [build, test-package]
+    runs-on: ubuntu-latest
+    if: |
+      (github.event_name == 'workflow_dispatch' && github.event.inputs.environment == 'production') ||
+      (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v'))
+    environment:
+      name: production
+      url: ${{ steps.deploy.outputs.url }}
+    
+    steps:
+    - name: Download dist
+      uses: actions/download-artifact@v3
+      with:
+        name: dist
+        path: dist/
+
+    - name: Deploy to PyPI
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+      run: |
+        python -m twine upload dist/*
+
+    - name: Set output URL
+      id: deploy
+      run: echo "url=https://pypi.org/project/ai-assistant/" >> $GITHUB_OUTPUT
+
+    - name: Create GitHub Release
+      if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+      uses: softprops/action-gh-release@v1
+      with:
+        files: dist/*
+        generate_release_notes: true
+
+  cleanup:
+    needs: [deploy-staging, deploy-production]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+    - name: Delete dist artifact
+      uses: geekyeggo/delete-artifact@v2
+      with:
+        name: dist 

.github/workflows/lint.yml

@@ -0,0 +1,98 @@
+name: Lint
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9"]
+
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: 'pip'
+    
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements-dev.txt
+    
+    - name: Check formatting with black
+      run: black . --check --diff
+    
+    - name: Check import sorting with isort
+      run: isort . --check --diff
+    
+    - name: Run flake8
+      run: flake8 .
+    
+    - name: Run pylint
+      run: pylint tools tests
+    
+    - name: Run mypy type checking
+      run: mypy .
+    
+    - name: Run bandit security checks
+      run: bandit -r . -c pyproject.toml
+    
+    - name: Run pyupgrade checks
+      run: |
+        find . -type f -name "*.py" -not -path "./venv/*" -not -path "./.env/*" -exec pyupgrade --py39-plus {} \;
+
+    - name: Verify pre-commit hooks
+      run: |
+        pre-commit install
+        pre-commit run --all-files
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.12"
+        cache: 'pip'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install bandit safety
+
+    - name: Run bandit
+      run: |
+        bandit -r tools -ll -ii
+
+    - name: Run safety check
+      run: |
+        safety check
+
+  dependency-review:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Dependency Review
+      uses: actions/dependency-review-action@v3
+      with:
+        fail-on-severity: moderate
+        deny-licenses: |
+          GPL-1.0
+          LGPL-2.0
+          BSD-2-Clause
+        allow-licenses: |
+          MIT
+          Apache-2.0
+          BSD-3-Clause 

.github/workflows/test.yml

@@ -0,0 +1,102 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+      fail-fast: false
+
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: 'pip'
+    
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements.txt
+        pip install -r requirements-dev.txt
+    
+    - name: Run tests with coverage
+      run: |
+        python scripts/run_tests.py
+      env:
+        PYTHONPATH: ${{ github.workspace }}
+    
+    - name: Upload coverage reports
+      uses: codecov/codecov-action@v3
+      with:
+        file: ./coverage.xml
+        flags: unittests
+        name: codecov-umbrella
+        fail_ci_if_error: true
+      if: success()
+    
+    - name: Upload coverage HTML report
+      uses: actions/upload-artifact@v3
+      with:
+        name: coverage-report-${{ matrix.python-version }}
+        path: coverage_html/
+        if-no-files-found: error
+      if: success()
+
+    - name: Upload test results
+      uses: actions/upload-artifact@v3
+      with:
+        name: pytest-results-${{ matrix.python-version }}
+        path: |
+          .coverage
+          coverage.xml
+          junit.xml
+        if-no-files-found: error
+      if: always()
+
+  coverage-badge:
+    needs: test
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Download coverage data
+      uses: actions/download-artifact@v3
+      with:
+        name: coverage-report-3.12
+        path: coverage_html/
+    
+    - name: Extract coverage percentage
+      run: |
+        COVERAGE=$(grep -o '[0-9]\+%' coverage_html/index.html | head -1 | tr -d '%')
+        echo "COVERAGE=$COVERAGE" >> $GITHUB_ENV
+        if [ "$COVERAGE" -ge 90 ]; then
+          echo "COVERAGE_COLOR=green" >> $GITHUB_ENV
+        elif [ "$COVERAGE" -ge 80 ]; then
+          echo "COVERAGE_COLOR=yellow" >> $GITHUB_ENV
+        else
+          echo "COVERAGE_COLOR=red" >> $GITHUB_ENV
+        fi
+    
+    - name: Create coverage badge
+      uses: schneegans/dynamic-badges-action@v1.6.0
+      with:
+        auth: ${{ secrets.GIST_SECRET }}
+        gistID: ${{ secrets.COVERAGE_GIST_ID }}
+        filename: coverage.json
+        label: coverage
+        message: ${{ env.COVERAGE }}%
+        color: ${{ env.COVERAGE_COLOR }}
+        namedLogo: python 

.pre-commit-config.yaml

@@ -0,0 +1,170 @@
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+    -   id: check-added-large-files
+        args: ['--maxkb=1024']
+    -   id: check-ast
+    -   id: check-case-conflict
+    -   id: check-docstring-first
+    -   id: check-executables-have-shebangs
+    -   id: check-json
+    -   id: check-merge-conflict
+    -   id: check-toml
+    -   id: check-yaml
+    -   id: debug-statements
+    -   id: detect-private-key
+    -   id: end-of-file-fixer
+    -   id: trailing-whitespace
+    -   id: mixed-line-ending
+        args: ['--fix=lf']
+
+-   repo: https://github.com/psf/black
+    rev: 24.2.0
+    hooks:
+    -   id: black
+        language_version: python3
+        args: ['--config=pyproject.toml']
+
+-   repo: https://github.com/pycqa/isort
+    rev: 5.13.2
+    hooks:
+    -   id: isort
+        args: ['--settings-path=pyproject.toml']
+
+-   repo: https://github.com/pycqa/flake8
+    rev: 7.0.0
+    hooks:
+    -   id: flake8
+        additional_dependencies:
+            - flake8-docstrings
+            - flake8-bugbear
+            - flake8-comprehensions
+            - flake8-simplify
+            - flake8-pytest-style
+            - flake8-typing-imports
+            - pep8-naming
+            - flake8-cognitive-complexity
+            - flake8-expression-complexity
+            - mccabe
+            - flake8-functions
+            - flake8-annotations-complexity
+
+-   repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.8.0
+    hooks:
+    -   id: mypy
+        additional_dependencies:
+            - types-requests
+            - types-PyYAML
+            - pydantic
+            - types-setuptools
+            - types-python-dateutil
+            - types-pytz
+            - types-urllib3
+            - types-six
+            - types-protobuf
+            - types-mock
+            - types-toml
+        args: [
+            '--config-file=pyproject.toml',
+            '--strict',
+            '--ignore-missing-imports',
+            '--python-version=3.9',
+            '--show-error-codes',
+            '--pretty',
+            '--warn-unused-ignores',
+            '--disallow-any-generics',
+            '--disallow-untyped-decorators',
+            '--no-implicit-optional'
+        ]
+
+-   repo: https://github.com/microsoft/pyright
+    rev: 1.1.350
+    hooks:
+    -   id: pyright
+        additional_dependencies:
+            - pydantic
+            - requests
+            - PyYAML
+        args: [
+            '--warnings',
+            '--pythonversion', '3.9',
+            '--typeCheckingMode', 'strict'
+        ]
+
+-   repo: https://github.com/RobertCraigie/pyright-python
+    rev: v1.1.350
+    hooks:
+    -   id: pyright-python
+        name: pyright-strict
+        args: [
+            '--warnings',
+            '--pythonversion', '3.9',
+            '--typeCheckingMode', 'strict',
+            '--ignoreexternal'
+        ]
+
+-   repo: https://github.com/PyCQA/bandit
+    rev: 1.7.7
+    hooks:
+    -   id: bandit
+        args: ['-c', 'pyproject.toml']
+
+-   repo: https://github.com/asottile/pyupgrade
+    rev: v3.15.1
+    hooks:
+    -   id: pyupgrade
+        args: ['--py39-plus']
+
+-   repo: https://github.com/PyCQA/doc8
+    rev: v1.1.1
+    hooks:
+    -   id: doc8
+        args: ['--max-line-length=120']
+
+-   repo: https://github.com/pypa/safety
+    rev: 2.3.5
+    hooks:
+    -   id: safety
+        args: ['check']
+
+-   repo: local
+    hooks:
+    -   id: pylint
+        name: pylint
+        entry: pylint
+        language: system
+        types: [python]
+        args:
+            - --rcfile=pyproject.toml
+            - --score=no
+            - --output-format=colorized
+
+    -   id: pytest-check
+        name: pytest-check
+        entry: pytest
+        language: system
+        pass_filenames: false
+        always_run: true
+        args:
+            - --cov
+            - --cov-report=term-missing
+            - -v
+
+-   repo: https://github.com/rubik/radon
+    rev: v6.0.1
+    hooks:
+    -   id: radon
+        name: radon-complexity
+        entry: radon cc
+        args: [--min=C, --total-average, --show-complexity]
+        language: python
+        types: [python]
+
+    -   id: radon-maintainability
+        name: radon-maintainability
+        entry: radon mi
+        args: [--min=B, --show]
+        language: python
+        types: [python]

CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial project structure and setup
+- Comprehensive code formatting standards
+  - Black configuration with 100 character line length
+  - isort for import sorting
+  - EditorConfig for consistent formatting
+- Static type checking configuration
+  - MyPy with strict type checking
+  - Pyright integration
+  - Type stubs for common dependencies
+- Code quality tools
+  - Flake8 with multiple plugins
+  - Radon for complexity checks
+  - Bandit for security scanning
+- Testing framework
+  - Pytest configuration
+  - Coverage reporting setup
+  - Test helpers and fixtures
+- Documentation
+  - Project README
+  - Contributing guidelines
+  - Code style guide
+  - Type checking guide
+- CI/CD Pipeline
+  - GitHub Actions workflow
+  - Pre-commit hooks configuration
+  - Automated testing and linting
+- Development tools
+  - Development requirements
+  - Virtual environment setup
+  - Local development guide
+
+### Changed
+- None (initial release)
+
+### Deprecated
+- None
+
+### Removed
+- None
+
+### Fixed
+- None
+
+### Security
+- Added Bandit security checks
+- Implemented Safety dependency scanning
+- Configured security-focused pre-commit hooks
+- Added checks for hardcoded secrets
+
+## [0.1.0] - YYYY-MM-DD
+### Added
+- First release of the project
+- Basic project structure
+- Core functionality implementation
+- Initial test suite
+- Basic documentation
+
+[Unreleased]: https://github.com/username/repository/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/username/repository/releases/tag/v0.1.0

CONTRIBUTING.md

@@ -0,0 +1,223 @@
+# Contributing Guidelines
+
+## Table of Contents
+- [Development Setup](#development-setup)
+- [Code Style](#code-style)
+- [Type Checking](#type-checking)
+- [Code Quality](#code-quality)
+- [Testing](#testing)
+- [Pull Request Process](#pull-request-process)
+- [Commit Guidelines](#commit-guidelines)
+
+## Development Setup
+
+### Prerequisites
+- Python 3.9+
+- pip
+- git
+
+### Setting Up Development Environment
+1. Clone the repository:
+   ```bash
+   git clone <repository-url>
+   cd <repository-name>
+   ```
+
+2. Create and activate a virtual environment:
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # Linux/macOS
+   .venv\Scripts\activate     # Windows
+   ```
+
+3. Install development dependencies:
+   ```bash
+   pip install -r requirements-dev.txt
+   ```
+
+4. Install pre-commit hooks:
+   ```bash
+   pre-commit install
+   ```
+
+## Code Style
+
+We follow a strict Python code style guide to maintain consistency across the project. Our code style is enforced through various tools:
+
+### Formatting
+- **Black**: Code formatting with line length of 100 characters
+- **isort**: Import sorting with three sections (stdlib, third-party, local)
+- **EditorConfig**: Editor-agnostic formatting rules
+
+### Style Rules
+- Use 4 spaces for indentation
+- Use meaningful variable and function names
+- Follow PEP 8 naming conventions
+- Write descriptive docstrings in Google style
+- Keep functions focused and concise
+
+Example:
+```python
+from typing import List, Optional
+
+def process_data(items: List[str], max_length: Optional[int] = None) -> List[str]:
+    """Process a list of string items with optional length limitation.
+
+    Args:
+        items: List of strings to process.
+        max_length: Optional maximum length for each string.
+
+    Returns:
+        List of processed strings.
+
+    Raises:
+        ValueError: If any string is empty.
+    """
+    if not items:
+        raise ValueError("Items list cannot be empty")
+
+    return [item[:max_length] if max_length else item for item in items]
+```
+
+## Type Checking
+
+We use multiple type checking tools to ensure type safety:
+
+### MyPy
+- Strict type checking enabled
+- All functions must have type annotations
+- Generic types must be fully specified
+- No implicit Optional types
+
+### Pyright
+- Strict mode enabled
+- Reports missing type stubs
+- Enforces strict collection type inference
+- Checks for proper None handling
+
+Example of proper type usage:
+```python
+from typing import Dict, List, Optional, TypeVar
+
+T = TypeVar("T")
+
+def merge_lists(list1: List[T], list2: List[T]) -> List[T]:
+    """Merge two lists of the same type."""
+    return list1 + list2
+
+def get_config(path: str) -> Dict[str, Optional[str]]:
+    """Get configuration with optional values."""
+    return {"key": "value", "optional_key": None}
+```
+
+## Code Quality
+
+We maintain high code quality standards through various tools:
+
+### Complexity Checks
+- Maximum cyclomatic complexity: C grade (radon)
+- Maximum cognitive complexity: 10 (flake8-cognitive-complexity)
+- Maximum function length: 50 lines
+- Maximum expression complexity: 3 (flake8-expression-complexity)
+
+### Security
+- Bandit security checks
+- Safety dependency checks
+- No hardcoded secrets
+- Proper error handling
+
+### Documentation
+- All public APIs must be documented
+- Complex algorithms need detailed explanations
+- Update documentation when changing functionality
+- Include examples in docstrings
+
+## Testing
+
+### Test Requirements
+- All new code must have tests
+- Maintain minimum 90% code coverage
+- Test both success and error cases
+- Use pytest fixtures for common setup
+
+### Running Tests
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov
+
+# Run specific test file
+pytest tests/test_specific.py
+```
+
+## Pull Request Process
+
+1. **Branch Naming**
+   - feature/description-of-feature
+   - bugfix/description-of-bug
+   - hotfix/description-of-hotfix
+
+2. **Before Submitting**
+   - Run all pre-commit hooks
+   - Ensure all tests pass
+   - Update documentation if needed
+   - Add tests for new features
+
+3. **PR Description**
+   - Clear description of changes
+   - Link to related issues
+   - List of testing steps
+   - Screenshots (if UI changes)
+
+4. **Review Process**
+   - At least one approval required
+   - All comments must be resolved
+   - CI checks must pass
+   - No merge conflicts
+
+## Commit Guidelines
+
+### Commit Message Format
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### Types
+- feat: New feature
+- fix: Bug fix
+- docs: Documentation
+- style: Formatting
+- refactor: Code restructuring
+- test: Adding tests
+- chore: Maintenance
+
+### Example
+```
+feat(auth): implement OAuth2 authentication
+
+- Add OAuth2 provider integration
+- Implement token refresh mechanism
+- Add user session management
+
+Closes #123
+```
+
+### Best Practices
+- Keep commits focused and atomic
+- Write clear commit messages
+- Reference issues in commits
+- Squash related commits
+
+## Questions or Problems?
+
+Feel free to:
+- Open an issue for questions
+- Join our community chat
+- Check existing documentation
+- Contact the maintainers

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 AI Assistant Team
+
+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. 

README.md

@@ -16,3 +16,675 @@ tags:
 ---
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+# AI Assistant Framework
+
+[![Tests](https://github.com/yourusername/ai-assistant/actions/workflows/test.yml/badge.svg)](https://github.com/yourusername/ai-assistant/actions/workflows/test.yml)
+[![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/yourusername/coverage.json)](https://github.com/yourusername/ai-assistant/actions/workflows/test.yml)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+A robust framework for building AI assistants with built-in error handling, logging, and API integration capabilities.
+
+## Features
+
+- 🛠 **Extensible Tool System**: Create and register custom tools with a simple interface
+- 🔄 **Error Recovery**: Built-in retry mechanism and circuit breaker pattern
+- 📝 **Comprehensive Logging**: Structured logging with security-aware data sanitization
+- 🔒 **Type Safety**: Full type hints and runtime type checking
+- 🌐 **API Integration**: Robust API error handling and rate limiting
+- ⚡ **Performance**: Efficient caching and resource management
+- 🧪 **Testing**: Extensive test coverage and mocking utilities
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install ai-assistant
+```
+
+### Basic Usage
+
+```python
+from tools import get_tool
+
+# Get a timezone tool
+timezone_tool = get_tool("timezone")
+
+# Use the tool
+current_time = timezone_tool.get_current_time("America/New_York")
+print(f"Current time: {current_time}")
+```
+
+### API Integration Example
+
+```python
+from tools.api_logging import log_api_call
+from tools.error_recovery import RetryConfig, CircuitBreaker
+
+@log_api_call(
+    retry_config=RetryConfig(max_retries=3),
+    circuit_breaker=CircuitBreaker(failure_threshold=5)
+)
+def get_weather(zipcode: str) -> dict:
+    # Your API call here
+    pass
+```
+
+## Documentation
+
+- [Getting Started Guide](docs/getting_started.md)
+- [API Reference](docs/api_reference.md)
+- [Error Handling Guide](docs/error_handling.md)
+- [Logging System](docs/logging.md)
+
+## Core Components
+
+### Tool Registry
+
+The framework uses a central registry for managing tools:
+
+```python
+from tools import ToolRegistry, register_tool
+
+@register_tool
+class MyCustomTool(BaseTool):
+    @property
+    def name(self) -> str:
+        return "my_tool"
+```
+
+### Error Recovery
+
+Built-in support for handling API errors:
+
+```python
+from tools.exceptions import APIError, APITimeoutError
+
+try:
+    result = api_call()
+except APITimeoutError as e:
+    print(f"Timeout after {e.timeout}s")
+```
+
+### Logging System
+
+Comprehensive logging with security features:
+
+```python
+@log_api_call(
+    log_response=True,
+    log_request_body=True
+)
+def secure_api_call():
+    # Sensitive data is automatically sanitized
+    pass
+```
+
+## Development
+
+### Prerequisites
+
+- Python 3.9+
+- pip
+
+### Setup
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/yourusername/ai-assistant.git
+   cd ai-assistant
+   ```
+
+2. Create a virtual environment:
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # Linux/Mac
+   # or
+   .\venv\Scripts\activate  # Windows
+   ```
+
+3. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   pip install -r requirements-dev.txt
+   ```
+
+### Running Tests
+
+```bash
+python scripts/run_tests.py
+```
+
+### Code Quality
+
+```bash
+# Format code
+black .
+
+# Type checking
+mypy tools tests
+
+# Linting
+flake8
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Commit your changes
+4. Push to the branch
+5. Create a Pull Request
+
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and development process.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- Thanks to all contributors who have helped shape this framework
+- Special thanks to the open source community for their invaluable tools and libraries
+
+# AI Assistant Application
+
+A Python-based AI assistant application that provides weather information and timezone conversions through a user-friendly Gradio interface.
+
+## Features
+
+- Weather information lookup by zip code using WeatherAPI
+- Timezone conversion functionality
+- Rate limiting for API calls
+- Configurable UI with Gradio
+- Comprehensive error handling
+- Logging system
+
+## Prerequisites
+
+- Python 3.8 or higher
+- pip package manager
+
+## Installation
+
+1. Clone the repository:
+```bash
+git clone <repository-url>
+cd <repository-name>
+```
+
+2. Create and activate a virtual environment:
+```bash
+python3 -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+```
+
+3. Install dependencies:
+```bash
+pip install -r requirements.txt
+```
+
+4. Create a `.env` file in the project root and configure your environment variables:
+```
+WEATHER_API_KEY=your_weather_api_key_here
+```
+
+## Configuration
+
+The application can be configured through:
+- `.env` file for environment variables
+- `config.py` for application settings
+- `prompts.yaml` for AI assistant prompts
+
+## Project Structure
+
+```
+.
+├── app.py              # Main application file
+├── config.py           # Configuration settings
+├── rate_limiter.py     # Rate limiting implementation
+├── ui.py              # Gradio UI implementation
+├── tools/             # Tool implementations
+│   ├── __init__.py
+│   └── final_answer.py
+├── prompts.yaml       # AI assistant prompts
+├── requirements.txt   # Project dependencies
+└── .env              # Environment variables
+```
+
+## Usage
+
+1. Ensure your virtual environment is activated
+2. Run the application:
+```bash
+python app.py
+```
+3. Open your web browser and navigate to the URL shown in the console
+
+## Error Handling
+
+The application includes comprehensive error handling for:
+- API rate limits
+- Invalid inputs
+- Network errors
+- Configuration issues
+
+## Logging
+
+Logs are written to `assistant.log` with configurable log levels through the `.env` file.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Commit your changes
+4. Push to the branch
+5. Create a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+# AI Assistant Configuration Guide
+
+This document provides a comprehensive guide to configuring the AI Assistant application. Configuration can be managed through environment variables or a JSON configuration file.
+
+## Table of Contents
+- [Environment Variables](#environment-variables)
+- [Configuration Options](#configuration-options)
+  - [Weather API Configuration](#weather-api-configuration)
+  - [Timezone API Configuration](#timezone-api-configuration)
+  - [Assistant Configuration](#assistant-configuration)
+  - [UI Configuration](#ui-configuration)
+  - [Logging Configuration](#logging-configuration)
+  - [Model Configuration](#model-configuration)
+- [Usage Examples](#usage-examples)
+
+## Environment Variables
+
+All configuration options can be set via environment variables. Environment variables take precedence over JSON configuration. Create a `.env` file in the project root to set these variables.
+
+Example `.env` file:
+```bash
+WEATHER_API_KEY=your_api_key_here
+LOG_LEVEL=INFO
+UI_THEME=dark
+```
+
+## Configuration Options
+
+### Weather API Configuration
+
+Controls the weather service API settings.
+
+| Option | Environment Variable | Default | Description |
+|--------|---------------------|---------|-------------|
+| `base_url` | `WEATHER_API_BASE_URL` | `http://api.weatherapi.com/v1` | Base URL for the weather API |
+| `rate_limit_per_minute` | `WEATHER_API_RATE_LIMIT` | `60` | Maximum API calls per minute |
+| `cache_timeout_seconds` | `WEATHER_CACHE_TIMEOUT` | `300` | How long to cache weather data |
+| `api_key` | `WEATHER_API_KEY` | `None` | Your weather API key |
+
+### Timezone API Configuration
+
+Controls the timezone service API settings.
+
+| Option | Environment Variable | Default | Description |
+|--------|---------------------|---------|-------------|
+| `rate_limit_per_minute` | `TIMEZONE_API_RATE_LIMIT` | `100` | Maximum API calls per minute |
+
+### Assistant Configuration
+
+Controls the AI Assistant's behavior.
+
+#### Command History
+| Option | Environment Variable | Default | Description |
+|--------|---------------------|---------|-------------|
+| `max_size` | `COMMAND_HISTORY_MAX_SIZE` | `10` | Maximum number of commands to remember |
+
+#### Cache Settings
+| Option | Environment Variable | Default | Description |
+|--------|---------------------|---------|-------------|
+| `cleanup_interval_seconds` | `CACHE_CLEANUP_INTERVAL` | `600` | Interval between cache cleanup operations |
+
+### UI Configuration
+
+Controls the user interface appearance and behavior.
+
+| Option | Environment Variable | Default | Description |
+|--------|---------------------|---------|-------------|
+| `title` | `UI_TITLE` | `AI Assistant` | Application title |
+| `description` | `UI_DESCRIPTION` | `Weather and Timezone Assistant` | Application description |
+| `theme` | `UI_THEME` | `light` | UI theme (`light` or `dark`) |
+| `input_placeholder` | `UI_INPUT_PLACEHOLDER` | `Enter your command (type 'help' for available commands)` | Input field placeholder text |
+| `width` | `UI_WIDTH` | `100%` | UI width (CSS units) |
+| `height` | `UI_HEIGHT` | `600px` | UI height (CSS units) |
+
+### Logging Configuration
+
+Controls application logging behavior.
+
+| Option | Environment Variable | Default | Description |
+|--------|---------------------|---------|-------------|
+| `level` | `LOG_LEVEL` | `INFO` | Log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`) |
+| `file` | `LOG_FILE` | `assistant.log` | Log file path |
+| `format` | `LOG_FORMAT` | `%(asctime)s - %(name)s - %(levelname)s - %(message)s` | Log message format |
+
+### Model Configuration
+
+Controls the AI model behavior.
+
+| Option | Environment Variable | Default | Description |
+|--------|---------------------|---------|-------------|
+| `class_name` | `MODEL_CLASS` | `HfApiModel` | Model class to use |
+| `max_tokens` | `MODEL_MAX_TOKENS` | `2096` | Maximum tokens per response |
+| `temperature` | `MODEL_TEMPERATURE` | `0.5` | Response randomness (0.0-1.0) |
+| `model_id` | `MODEL_ID` | `Qwen/Qwen2.5-Coder-32B-Instruct` | Model identifier |
+
+## Usage Examples
+
+### Using Environment Variables
+
+```bash
+# Set weather API configuration
+export WEATHER_API_KEY=your_api_key_here
+export WEATHER_API_RATE_LIMIT=30
+
+# Configure logging
+export LOG_LEVEL=DEBUG
+export LOG_FILE=logs/assistant.log
+
+# Set UI preferences
+export UI_THEME=dark
+export UI_WIDTH=80%
+```
+
+### Using JSON Configuration
+
+Create a `config.json` file:
+
+```json
+{
+  "config": {
+    "api": {
+      "weather": {
+        "base_url": "http://api.weatherapi.com/v1",
+        "rate_limit_per_minute": 30,
+        "cache_timeout_seconds": 600
+      },
+      "timezone": {
+        "rate_limit_per_minute": 50
+      }
+    },
+    "assistant": {
+      "command_history": {
+        "max_size": 20
+      },
+      "cache": {
+        "cleanup_interval_seconds": 300
+      }
+    },
+    "ui": {
+      "theme": "dark",
+      "width": "80%",
+      "height": "800px"
+    },
+    "logging": {
+      "level": "DEBUG",
+      "file": "logs/debug.log"
+    }
+  },
+  "model": {
+    "class": "HfApiModel",
+    "data": {
+      "max_tokens": 1024,
+      "temperature": 0.7,
+      "model_id": "Qwen/Qwen2.5-Coder-32B-Instruct"
+    }
+  }
+}
+```
+
+### Loading Configuration in Code
+
+```python
+from config import Config
+
+# Load from environment variables
+config = Config()
+
+# Or load from JSON file
+with open('config.json') as f:
+    import json
+    config = Config.from_json(json.load(f))
+
+# Access configuration
+weather_url = config.api.weather.base_url
+log_level = config.logging.level
+ui_theme = config.ui.theme
+```
+
+## Validation
+
+The configuration system includes comprehensive validation:
+
+- All numeric values are checked for valid ranges
+- URLs are validated for correct format
+- File paths are checked for existence/createability
+- Enums (like log levels and themes) are validated against allowed values
+- Cross-field validation ensures consistent configuration
+
+If validation fails, a `ConfigValidationError` is raised with a descriptive message and the field name that caused the error.
+
+# API Configuration Guide
+
+This document describes all available configuration options for the API client. Configuration can be provided via environment variables or a JSON configuration file.
+
+## Table of Contents
+- [Configuration Methods](#configuration-methods)
+- [Base Configuration](#base-configuration)
+- [Connection Pool Settings](#connection-pool-settings)
+- [Rate Limiting Settings](#rate-limiting-settings)
+- [Batch Processing Settings](#batch-processing-settings)
+- [Monitoring Settings](#monitoring-settings)
+- [Retry Settings](#retry-settings)
+- [Environment Variables](#environment-variables)
+- [Examples](#examples)
+
+## Configuration Methods
+
+Configuration can be provided in two ways:
+
+1. **Environment Variables**: Set using the format `API_<SECTION>_<SETTING>`
+2. **JSON Configuration File**: Provide settings in `agent.json`
+
+Environment variables take precedence over file-based configuration.
+
+## Base Configuration
+
+| Setting    | Description           | Type     | Required | Default             | Validation                    |
+|------------|--------------------|----------|----------|---------------------|-------------------------------|
+| `base_url` | Base URL for API   | string   | Yes      | http://localhost:8000 | Must be valid HTTP/HTTPS URL |
+
+## Connection Pool Settings
+
+| Setting            | Description                  | Type    | Default | Range        | Environment Variable              |
+|-------------------|------------------------------|---------|---------|--------------|----------------------------------|
+| `pool_size`       | Maximum connections          | integer | 10      | 1-100       | `API_CONNECTION_POOL_SIZE`       |
+| `timeout`         | Connection timeout (seconds) | float   | 30.0    | 0.0-300.0   | `API_CONNECTION_TIMEOUT`         |
+| `keepalive_timeout` | Keep-alive timeout (seconds) | float   | None    | 0.0-300.0   | `API_CONNECTION_KEEPALIVE_TIMEOUT` |
+| `ttl_dns_cache`   | DNS cache TTL (seconds)     | integer | None    | 0-3600      | `API_CONNECTION_TTL_DNS_CACHE`   |
+| `force_close`     | Force close connections      | boolean | false   | true/false  | `API_CONNECTION_FORCE_CLOSE`     |
+
+**Validation Rules**:
+- `keepalive_timeout` must be less than or equal to `timeout`
+- `pool_size` should be set based on expected concurrent connections
+
+## Rate Limiting Settings
+
+| Setting   | Description            | Type    | Default | Range      | Environment Variable    |
+|-----------|------------------------|---------|---------|------------|------------------------|
+| `rate`    | Requests per second    | float   | 10.0    | 0.1-1000.0 | `API_RATE_LIMIT_RATE`  |
+| `burst`   | Maximum burst size     | integer | 20      | 1-2000     | `API_RATE_LIMIT_BURST` |
+| `enabled` | Enable rate limiting   | boolean | true    | true/false | `API_RATE_LIMIT_ENABLED` |
+
+**Validation Rules**:
+- `burst` must be greater than or equal to `rate`
+- `burst` must not exceed 10x the `rate`
+- Recommended: Set `burst` to 2-3x the `rate` for normal operation
+
+## Batch Processing Settings
+
+| Setting    | Description              | Type    | Default | Range     | Environment Variable  |
+|------------|-------------------------|---------|---------|-----------|---------------------|
+| `size`     | Maximum items per batch | integer | 100     | 1-1000    | `API_BATCH_SIZE`     |
+| `interval` | Flush interval (seconds)| float   | 1.0     | 0.1-60.0  | `API_BATCH_INTERVAL` |
+| `enabled`  | Enable batch processing | boolean | true    | true/false| `API_BATCH_ENABLED`  |
+
+**Best Practices**:
+- Set `size` based on your API's batch processing capabilities
+- Adjust `interval` based on latency requirements and load
+
+## Monitoring Settings
+
+| Setting        | Description                    | Type    | Default | Range      | Environment Variable           |
+|----------------|--------------------------------|---------|---------|------------|-------------------------------|
+| `metrics_ttl`  | Metrics TTL (seconds)          | integer | 3600    | 0-86400    | `API_MONITORING_METRICS_TTL`  |
+| `max_metrics`  | Maximum metrics to store       | integer | 1000    | 1-10000    | `API_MONITORING_MAX_METRICS`  |
+| `log_interval` | Metrics logging interval (sec) | float   | 60.0    | 0.1-3600.0 | `API_MONITORING_LOG_INTERVAL` |
+| `enabled`      | Enable monitoring              | boolean | true    | true/false | `API_MONITORING_ENABLED`      |
+
+**Validation Rules**:
+- `log_interval` must be less than `metrics_ttl`
+- Consider memory usage when setting `max_metrics`
+
+## Retry Settings
+
+| Setting        | Description                     | Type    | Default | Range      | Environment Variable      |
+|----------------|---------------------------------|---------|---------|------------|-------------------------|
+| `max_attempts` | Maximum retry attempts          | integer | 3       | 1-10       | `API_RETRY_MAX_ATTEMPTS` |
+| `min_wait`     | Minimum wait time (seconds)     | float   | 1.0     | 0.1-60.0   | `API_RETRY_MIN_WAIT`     |
+| `max_wait`     | Maximum wait time (seconds)     | float   | 10.0    | 0.1-300.0  | `API_RETRY_MAX_WAIT`     |
+| `enabled`      | Enable retry mechanism          | boolean | true    | true/false | `API_RETRY_ENABLED`      |
+
+**Validation Rules**:
+- `max_wait` must be greater than `min_wait`
+- `max_wait` must not exceed 10x `min_wait`
+- Uses exponential backoff between `min_wait` and `max_wait`
+
+## Environment Variables
+
+All settings can be configured using environment variables. Example `.env` file:
+
+```bash
+# Base Configuration
+API_BASE_URL=http://api.example.com
+
+# Connection Pool
+API_CONNECTION_POOL_SIZE=20
+API_CONNECTION_TIMEOUT=30.0
+API_CONNECTION_KEEPALIVE_TIMEOUT=60.0
+API_CONNECTION_TTL_DNS_CACHE=300
+API_CONNECTION_FORCE_CLOSE=false
+
+# Rate Limiting
+API_RATE_LIMIT_RATE=50.0
+API_RATE_LIMIT_BURST=100
+API_RATE_LIMIT_ENABLED=true
+
+# Batch Processing
+API_BATCH_SIZE=500
+API_BATCH_INTERVAL=2.0
+API_BATCH_ENABLED=true
+
+# Monitoring
+API_MONITORING_METRICS_TTL=7200
+API_MONITORING_MAX_METRICS=5000
+API_MONITORING_LOG_INTERVAL=300.0
+API_MONITORING_ENABLED=true
+
+# Retry
+API_RETRY_MAX_ATTEMPTS=5
+API_RETRY_MIN_WAIT=1.0
+API_RETRY_MAX_WAIT=30.0
+API_RETRY_ENABLED=true
+```
+
+## Examples
+
+### Minimal Configuration
+
+```json
+{
+  "config": {
+    "base_url": "http://api.example.com"
+  }
+}
+```
+
+### High-Performance Configuration
+
+```json
+{
+  "config": {
+    "base_url": "http://api.example.com",
+    "connection_pool": {
+      "pool_size": 50,
+      "timeout": 60.0,
+      "keepalive_timeout": 30.0,
+      "ttl_dns_cache": 300
+    },
+    "rate_limit": {
+      "rate": 100.0,
+      "burst": 200
+    },
+    "batch": {
+      "size": 500,
+      "interval": 2.0
+    }
+  }
+}
+```
+
+### High-Reliability Configuration
+
+```json
+{
+  "config": {
+    "base_url": "http://api.example.com",
+    "retry": {
+      "max_attempts": 5,
+      "min_wait": 1.0,
+      "max_wait": 30.0
+    },
+    "monitoring": {
+      "metrics_ttl": 7200,
+      "max_metrics": 5000,
+      "log_interval": 300.0
+    }
+  }
+}
+```
+
+### Development Configuration
+
+```json
+{
+  "config": {
+    "base_url": "http://localhost:8000",
+    "connection_pool": {
+      "pool_size": 5,
+      "timeout": 5.0
+    },
+    "rate_limit": {
+      "rate": 10.0,
+      "burst": 20
+    },
+    "monitoring": {
+      "metrics_ttl": 3600,
+      "max_metrics": 1000,
+      "log_interval": 60.0
+    }
+  }
+}
+```

SECURITY.md

@@ -0,0 +1,283 @@
+# Security Best Practices
+
+This document outlines security best practices for using the API key management system.
+
+## Table of Contents
+1. [API Key Management](#api-key-management)
+2. [Rate Limiting](#rate-limiting)
+3. [Key Storage](#key-storage)
+4. [Environment Variables](#environment-variables)
+5. [Error Handling](#error-handling)
+6. [Encryption](#encryption)
+7. [Monitoring and Logging](#monitoring-and-logging)
+8. [Security Checklist](#security-checklist)
+
+## API Key Management
+
+### Key Generation
+- Use cryptographically secure random generators for API keys
+- Minimum key length: 32 characters
+- Use URL-safe characters: `[A-Za-z0-9_.-]`
+- Example:
+  ```python
+  import secrets
+  import string
+
+  def generate_api_key(length: int = 32) -> str:
+      alphabet = string.ascii_letters + string.digits + '_.-'
+      return ''.join(secrets.choice(alphabet) for _ in range(length))
+  ```
+
+### Key Rotation
+- Rotate keys regularly (recommended: every 90 days)
+- Implement automatic key expiration
+- Keep old keys active during transition period
+- Use the `rotate_key()` method:
+  ```python
+  from datetime import datetime, timedelta, timezone
+
+  # Rotate key with 7-day overlap
+  new_key = key_manager.rotate_key(
+      name="service_name",
+      new_key=generate_api_key(),
+      expires_at=datetime.now(timezone.utc) + timedelta(days=90)
+  )
+  ```
+
+### Access Control
+- Use scoped access for fine-grained control
+- Implement the principle of least privilege
+- Regularly audit key usage and permissions
+- Example scopes:
+  ```python
+  key_manager.add_key(
+      name="read_only_key",
+      key=generate_api_key(),
+      scopes=["read:data", "list:items"]
+  )
+  ```
+
+## Rate Limiting
+
+### Configuration
+- Set appropriate rate limits based on service capacity
+- Configure burst limits for handling traffic spikes
+- Monitor rate limit violations
+- Example:
+  ```python
+  key_manager.add_key(
+      name="high_throughput",
+      key=generate_api_key(),
+      rate_limit=100.0,    # 100 requests per second
+      burst_limit=200      # Allow bursts up to 200
+  )
+  ```
+
+### Best Practices
+- Implement client-side rate limiting
+- Use exponential backoff for retries
+- Monitor rate limit errors
+- Handle rate limit errors gracefully:
+  ```python
+  try:
+      wait_time = await key_manager.check_rate_limit("my_key")
+      if wait_time > 0:
+          # Implement backoff strategy
+          await asyncio.sleep(wait_time)
+  except RateLimitError as e:
+      # Handle rate limit exceeded
+      logger.warning(f"Rate limit exceeded: {e}")
+  ```
+
+## Key Storage
+
+### File Storage
+- Use encrypted storage for API keys
+- Secure file permissions (600 or more restrictive)
+- Regular backups of key storage
+- Example file permissions:
+  ```bash
+  chmod 600 keys.json
+  chown service_user:service_group keys.json
+  ```
+
+### Memory Storage
+- Never log API keys
+- Clear sensitive data from memory when no longer needed
+- Use secure string handling:
+  ```python
+  from pydantic import SecretStr
+
+  # Keys are automatically masked in logs/str representation
+  key_config = APIKeyConfig(
+      key=SecretStr("my-secret-key"),
+      name="service_name"
+  )
+  ```
+
+## Environment Variables
+
+### Configuration
+- Use environment variables for sensitive data
+- Follow naming conventions
+- Set appropriate file permissions for env files
+- Example `.env` file:
+  ```bash
+  # API Keys
+  API_SERVICE_KEY=your-secret-key
+  API_SERVICE_RATE_LIMIT=100
+  API_SERVICE_BURST_LIMIT=200
+
+  # Encryption
+  API_ENCRYPTION_KEY=your-encryption-key
+  ```
+
+### Security Measures
+- Never commit `.env` files to version control
+- Use different keys for different environments
+- Rotate environment variables regularly
+- Example `.gitignore`:
+  ```
+  .env
+  *.key
+  keys.json
+  ```
+
+## Error Handling
+
+### Best Practices
+- Use specific error types for different security issues
+- Never expose sensitive information in error messages
+- Log security events appropriately
+- Example:
+  ```python
+  try:
+      key = key_manager.get_key("service_name")
+  except InvalidKeyError:
+      # Log the error, but don't expose key details
+      logger.error("Invalid API key used", extra={
+          "service": "service_name",
+          "error_type": "invalid_key"
+      })
+      raise HTTPError(401, "Authentication failed")
+  ```
+
+### Error Types
+- `SecurityError`: Base class for security errors
+- `AuthenticationError`: Authentication failures
+- `AuthorizationError`: Permission issues
+- `InvalidKeyError`: Invalid/missing keys
+- `KeyExpiredError`: Expired keys
+- `RateLimitError`: Rate limit violations
+- `EncryptionError`: Encryption issues
+- `ValidationError`: Input validation failures
+- `ConfigurationError`: Configuration issues
+
+## Encryption
+
+### Key Management
+- Use strong encryption keys (min 32 bytes)
+- Regular rotation of encryption keys
+- Secure key storage
+- Example:
+  ```python
+  import base64
+  import os
+
+  # Generate new encryption key
+  encryption_key = base64.urlsafe_b64encode(os.urandom(32)).decode()
+  ```
+
+### Best Practices
+- Use industry-standard encryption (Fernet)
+- Implement key rotation
+- Secure key transmission
+- Example:
+  ```python
+  from cryptography.fernet import Fernet
+
+  # Initialize with encryption key
+  key_manager = KeyManager(
+      encryption_key=os.getenv("API_ENCRYPTION_KEY")
+  )
+  ```
+
+## Monitoring and Logging
+
+### Security Events
+- Log all security-related events
+- Use appropriate log levels
+- Include relevant context
+- Example:
+  ```python
+  import structlog
+
+  logger = structlog.get_logger()
+
+  # Log security event
+  logger.warning("rate_limit_exceeded",
+      key_name="service_name",
+      wait_time=1.5,
+      threshold=100
+  )
+  ```
+
+### Monitoring
+- Monitor failed authentication attempts
+- Track rate limit violations
+- Alert on suspicious activity
+- Example metrics:
+  ```python
+  # Track security metrics
+  metrics = {
+      "failed_auth_attempts": counter,
+      "rate_limit_violations": counter,
+      "key_rotations": counter,
+      "encryption_errors": counter
+  }
+  ```
+
+## Security Checklist
+
+### Implementation
+- [ ] Use secure random API key generation
+- [ ] Implement key rotation
+- [ ] Configure appropriate rate limits
+- [ ] Set up encrypted storage
+- [ ] Use environment variables
+- [ ] Implement proper error handling
+- [ ] Set up security logging
+- [ ] Configure monitoring
+
+### Deployment
+- [ ] Secure file permissions
+- [ ] Environment separation
+- [ ] Backup strategy
+- [ ] Monitoring setup
+- [ ] Alert configuration
+- [ ] Audit logging
+- [ ] Regular security reviews
+
+### Maintenance
+- [ ] Regular key rotation
+- [ ] Log review
+- [ ] Security updates
+- [ ] Access audit
+- [ ] Performance monitoring
+- [ ] Incident response plan
+- [ ] Documentation updates
+
+## Reporting Security Issues
+
+If you discover a security vulnerability, please follow these steps:
+
+1. **DO NOT** open a public issue
+2. Send a private report to [security@example.com]
+3. Include detailed information about the vulnerability
+4. Wait for confirmation before any disclosure
+
+## Updates and Changes
+
+This security documentation is regularly reviewed and updated. Last update: [Current Date]
+
+For questions or suggestions about security practices, please contact the security team.

STYLE_GUIDE.md

@@ -0,0 +1,220 @@
+# Python Code Style Guide
+
+## General Guidelines
+
+- Line length: 100 characters maximum
+- Indentation: 4 spaces (no tabs)
+- File encoding: UTF-8
+- Line endings: LF (Unix-style)
+- One blank line between functions and classes
+- Two blank lines between top-level functions and classes
+
+## Naming Conventions
+
+- Package names: `lowercase`
+- Module names: `lowercase_with_underscores`
+- Class names: `CapWords`
+- Function names: `lowercase_with_underscores`
+- Variable names: `lowercase_with_underscores`
+- Constants: `UPPERCASE_WITH_UNDERSCORES`
+- Protected attributes: `_leading_underscore`
+- Private attributes: `__double_leading_underscore`
+
+## Imports
+
+- Order imports in three groups, separated by a blank line:
+  1. Standard library imports
+  2. Third-party imports
+  3. Local application imports
+- Use absolute imports over relative imports
+- One import per line
+- No wildcard imports (`from module import *`)
+
+Example:
+```python
+import os
+import sys
+from typing import Dict, List, Optional
+
+import requests
+from pydantic import BaseModel
+
+from tools.config import Config
+from tools.utils import format_response
+```
+
+## String Formatting
+
+- Use f-strings for string formatting
+- Use raw strings (`r"..."`) for regular expressions
+- Use triple quotes for docstrings and multiline strings
+
+Example:
+```python
+name = "World"
+greeting = f"Hello, {name}!"
+pattern = r"^\d{3}-\d{2}-\d{4}$"
+```
+
+## Type Hints
+
+- Use type hints for all function arguments and return values
+- Use `Optional` for nullable values
+- Use `Union` for multiple possible types
+- Use `Any` sparingly and document why when used
+
+Example:
+```python
+def process_data(
+    input_data: Dict[str, Any],
+    max_items: Optional[int] = None,
+) -> List[str]:
+    """Process input data and return list of strings."""
+```
+
+## Docstrings
+
+- Use Google-style docstrings
+- Include Args, Returns, Raises sections when applicable
+- Document exceptions that may be raised
+- Include type information in docstring descriptions
+
+Example:
+```python
+def calculate_average(numbers: List[float]) -> float:
+    """Calculate the average of a list of numbers.
+
+    Args:
+        numbers: List of numbers to average.
+            Must be non-empty list of floats.
+
+    Returns:
+        float: The arithmetic mean of the input numbers.
+
+    Raises:
+        ValueError: If the input list is empty.
+        TypeError: If any element is not a number.
+    """
+```
+
+## Classes
+
+- Use dataclasses or Pydantic models for data containers
+- Implement `__repr__` for debugging
+- Use properties instead of getter/setter methods
+- Document class attributes in class docstring
+
+Example:
+```python
+from dataclasses import dataclass
+from datetime import datetime
+
+@dataclass
+class User:
+    """User information container.
+
+    Attributes:
+        username: Unique identifier for the user
+        email: User's email address
+        created_at: Timestamp of user creation
+    """
+    username: str
+    email: str
+    created_at: datetime = field(default_factory=datetime.utcnow)
+
+    def __repr__(self) -> str:
+        return f"User(username={self.username})"
+```
+
+## Error Handling
+
+- Use specific exception types
+- Always include error messages
+- Clean up resources in finally blocks
+- Use context managers when possible
+
+Example:
+```python
+try:
+    with open(filename, "r") as f:
+        data = f.read()
+except FileNotFoundError:
+    logger.error(f"Config file {filename} not found")
+    raise ConfigError(f"Missing configuration file: {filename}")
+except IOError as e:
+    logger.error(f"IO error reading {filename}: {e}")
+    raise
+```
+
+## Testing
+
+- Test file names: `test_*.py`
+- Test function names: `test_*`
+- Use descriptive test names
+- One assertion per test when possible
+- Use fixtures for setup/teardown
+
+Example:
+```python
+def test_user_creation_with_valid_data():
+    """Test user creation with valid input data."""
+    user = User(username="test", email="test@example.com")
+    assert user.username == "test"
+    assert user.email == "test@example.com"
+```
+
+## Comments
+
+- Write self-documenting code
+- Use comments to explain why, not what
+- Keep comments up-to-date with code
+- Use TODO comments with ticket numbers
+
+Example:
+```python
+# TODO(#123): Implement rate limiting for API calls
+def process_api_request():
+    # Temporary workaround for race condition
+    # Remove once transaction handling is implemented
+    time.sleep(0.1)
+```
+
+## Tools and Automation
+
+Our codebase is automatically formatted and checked using:
+
+- `black`: Code formatting
+- `isort`: Import sorting
+- `flake8`: Style guide enforcement
+- `mypy`: Type checking
+- `pylint`: Code analysis
+- `bandit`: Security checks
+
+Run all checks locally:
+```bash
+pre-commit run --all-files
+```
+
+## IDE Integration
+
+### VS Code Settings
+```json
+{
+    "python.formatting.provider": "black",
+    "python.linting.enabled": true,
+    "python.linting.flake8Enabled": true,
+    "python.linting.pylintEnabled": true,
+    "python.linting.mypyEnabled": true,
+    "editor.formatOnSave": true,
+    "editor.rulers": [100],
+    "files.trimTrailingWhitespace": true,
+    "files.insertFinalNewline": true
+}
+```
+
+### PyCharm Settings
+- Enable Black formatter
+- Enable Flake8 and PyLint
+- Set line length to 100
+- Enable "Optimize imports on the fly"
+- Enable "Add final newline on Save" 

agent.json

@@ -1,7 +1,59 @@
 {
     "tools": [
-        "get_weather_by_zipcode",
-        "final_answer"
+        {
+            "name": "WeatherTool",
+            "description": "Class-based tool for retrieving weather information by ZIP code",
+            "inputs": {
+                "zipcode": {
+                    "type": "string",
+                    "description": "5-digit US ZIP code"
+                }
+            },
+            "output_type": "string",
+            "output_description": "Formatted weather information including temperature, conditions, humidity, and wind",
+            "class_implementation": true
+        },
+        {
+            "name": "AIAssistant",
+            "description": "Main assistant class implementing core functionality",
+            "methods": {
+                "get_current_time_in_timezone": {
+                    "description": "Get current time in a specified timezone",
+                    "inputs": {
+                        "timezone": {
+                            "type": "string",
+                            "description": "Valid timezone name from pytz.all_timezones"
+                        }
+                    },
+                    "output_type": "string",
+                    "output_description": "Current time in the specified timezone format: YYYY-MM-DD HH:MM:SS TZ"
+                },
+                "get_matching_timezones": {
+                    "description": "Search for timezone names matching a partial string",
+                    "inputs": {
+                        "partial": {
+                            "type": "string",
+                            "description": "Partial timezone name to search for"
+                        }
+                    },
+                    "output_type": "list",
+                    "output_description": "List of timezone names containing the search string"
+                }
+            }
+        },
+        {
+            "name": "FinalAnswerTool",
+            "description": "Tool for providing the final answer to user queries",
+            "inputs": {
+                "answer": {
+                    "type": "any",
+                    "description": "The answer to be returned to the user"
+                }
+            },
+            "output_type": "string",
+            "output_description": "Formatted answer string",
+            "class_implementation": true
+        }
     ],
     "model": {
         "class": "HfApiModel",
@@ -15,26 +67,8 @@
         }
     },
     "prompt_templates": {
-        "system_prompt": "You are an expert assistant who can solve any task using code blobs. You will be given a task to solve as best you can.\nTo do so, you have been given access to a list of tools: these tools are basically Python functions which you can call with code.\nTo solve the task, you must plan forward to proceed in a series of steps, in a cycle of 'Thought:', 'Code:', and 'Observation:' sequences.\n\nAt each step, in the 'Thought:' sequence, you should first explain your reasoning towards solving the task and the tools that you want to use.\nThen in the 'Code:' sequence, you should write the code in simple Python. The code sequence must end with '<end_code>' sequence.\nDuring each intermediate step, you can use 'print()' to save whatever important information you will then need.\nThese print outputs will then appear in the 'Observation:' field, which will be available as input for the next step.\nIn the end you have to return a final answer using the `final_answer` tool.\n\nHere are a few examples using notional tools:\n---\nTask: \"Generate an image of the oldest person in this document.\"\n\nThought: I will proceed step by step and use the following tools: `document_qa` to find the oldest person in the document, then `image_generator` to generate an image according to the answer.\nCode:\n```py\nanswer = document_qa(document=document, question=\"Who is the oldest person mentioned?\")\nprint(answer)\n```<end_code>\nObservation: \"The oldest person in the document is John Doe, a 55 year old lumberjack living in Newfoundland.\"\n\nThought: I will now generate an image showcasing the oldest person.\nCode:\n```py\nimage = image_generator(\"A portrait of John Doe, a 55-year-old man living in Canada.\")\nfinal_answer(image)\n```<end_code>\n\n---\nTask: \"What is the result of the following operation: 5 + 3 + 1294.678?\"\n\nThought: I will use python code to compute the result of the operation and then return the final answer using the `final_answer` tool\nCode:\n```py\nresult = 5 + 3 + 1294.678\nfinal_answer(result)\n```<end_code>\n\n---\nTask:\n\"Answer the question in the variable `question` about the image stored in the variable `image`. The question is in French.\nYou have been provided with these additional arguments, that you can access using the keys as variables in your python code:\n{'question': 'Quel est l'animal sur l'image?', 'image': 'path/to/image.jpg'}\"\n\nThought: I will use the following tools: `translator` to translate the question into English and then `image_qa` to answer the question on the input image.\nCode:\n```py\ntranslated_question = translator(question=question, src_lang=\"French\", tgt_lang=\"English\")\nprint(f\"The translated question is {translated_question}.\")\nanswer = image_qa(image=image, question=translated_question)\nfinal_answer(f\"The answer is {answer}\")\n```<end_code>\n\n---\nTask:\nIn a 1979 interview, Stanislaus Ulam discusses with Martin Sherwin about other great physicists of his time, including Oppenheimer.\nWhat does he say was the consequence of Einstein learning too much math on his creativity, in one word?\n\nThought: I need to find and read the 1979 interview of Stanislaus Ulam with Martin Sherwin.\nCode:\n```py\npages = search(query=\"1979 interview Stanislaus Ulam Martin Sherwin physicists Einstein\")\nprint(pages)\n```<end_code>\nObservation:\nNo result found for query \"1979 interview Stanislaus Ulam Martin Sherwin physicists Einstein\".\n\nThought: The query was maybe too restrictive and did not find any results. Let's try again with a broader query.\nCode:\n```py\npages = search(query=\"1979 interview Stanislaus Ulam\")\nprint(pages)\n```<end_code>\nObservation:\nFound 6 pages:\n[Stanislaus Ulam 1979 interview](https://ahf.nuclearmuseum.org/voices/oral-histories/stanislaus-ulams-interview-1979/)\n\n[Ulam discusses Manhattan Project](https://ahf.nuclearmuseum.org/manhattan-project/ulam-manhattan-project/)\n\n(truncated)\n\nThought: I will read the first 2 pages to know more.\nCode:\n```py\nfor url in [\"https://ahf.nuclearmuseum.org/voices/oral-histories/stanislaus-ulams-interview-1979/\", \"https://ahf.nuclearmuseum.org/manhattan-project/ulam-manhattan-project/\"]:\n    whole_page = visit_webpage(url)\n    print(whole_page)\n    print(\"\\n\" + \"=\"*80 + \"\\n\")  # Print separator between pages\n```<end_code>\nObservation:\nManhattan Project Locations:\nLos Alamos, NM\nStanislaus Ulam was a Polish-American mathematician. He worked on the Manhattan Project at Los Alamos and later helped design the hydrogen bomb. In this interview, he discusses his work at\n(truncated)\n\nThought: I now have the final answer: from the webpages visited, Stanislaus Ulam says of Einstein: \"He learned too much mathematics and sort of diminished, it seems to me personally, it seems to me his purely physics creativity.\" Let's answer in one word.\nCode:\n```py\nfinal_answer(\"diminished\")\n```<end_code>\n\n---\nTask: \"Which city has the highest population: Guangzhou or Shanghai?\"\n\nThought: I need to get the populations for both cities and compare them: I will use the tool `search` to get the population of both cities.\nCode:\n```py\nfor city in [\"Guangzhou\", \"Shanghai\"]:\n    print(f\"Population {city}:\", search(f\"{city} population\")\n```<end_code>\nObservation:\nPopulation Guangzhou: ['Guangzhou has a population of 15 million inhabitants as of 2021.']\nPopulation Shanghai: '26 million (2019)'\n\nThought: Now I know that Shanghai has the highest population.\nCode:\n```py\nfinal_answer(\"Shanghai\")\n```<end_code>\n\n---\nTask: \"What is the current age of the pope, raised to the power 0.36?\"\n\nThought: I will use the tool `wiki` to get the age of the pope, and confirm that with a web search.\nCode:\n```py\npope_age_wiki = wiki(query=\"current pope age\")\nprint(\"Pope age as per wikipedia:\", pope_age_wiki)\npope_age_search = web_search(query=\"current pope age\")\nprint(\"Pope age as per google search:\", pope_age_search)\n```<end_code>\nObservation:\nPope age: \"The pope Francis is currently 88 years old.\"\n\nThought: I know that the pope is 88 years old. Let's compute the result using python code.\nCode:\n```py\npope_current_age = 88 ** 0.36\nfinal_answer(pope_current_age)\n```<end_code>\n\nAbove example were using notional tools that might not exist for you. On top of performing computations in the Python code snippets that you create, you only have access to these tools:\n{%- for tool in tools.values() %}\n- {{ tool.name }}: {{ tool.description }}\n    Takes inputs: {{tool.inputs}}\n    Returns an output of type: {{tool.output_type}}\n{%- endfor %}\n\n{%- if managed_agents and managed_agents.values() | list %}\nYou can also give tasks to team members.\nCalling a team member works the same as for calling a tool: simply, the only argument you can give in the call is 'task', a long string explaining your task.\nGiven that this team member is a real human, you should be very verbose in your task.\nHere is a list of the team members that you can call:\n{%- for agent in managed_agents.values() %}\n- {{ agent.name }}: {{ agent.description }}\n{%- endfor %}\n{%- else %}\n{%- endif %}\n\nHere are the rules you should always follow to solve your task:\n1. Always provide a 'Thought:' sequence, and a 'Code:\\n```py' sequence ending with '```<end_code>' sequence, else you will fail.\n2. Use only variables that you have defined!\n3. Always use the right arguments for the tools. DO NOT pass the arguments as a dict as in 'answer = wiki({'query': \"What is the place where James Bond lives?\"})', but use the arguments directly as in 'answer = wiki(query=\"What is the place where James Bond lives?\")'.\n4. Take care to not chain too many sequential tool calls in the same code block, especially when the output format is unpredictable. For instance, a call to search has an unpredictable return format, so do not have another tool call that depends on its output in the same block: rather output results with print() to use them in the next block.\n5. Call a tool only when needed, and never re-do a tool call that you previously did with the exact same parameters.\n6. Don't name any new variable with the same name as a tool: for instance don't name a variable 'final_answer'.\n7. Never create any notional variables in our code, as having these in your logs will derail you from the true variables.\n8. You can use imports in your code, but only from the following list of modules: {{authorized_imports}}\n9. The state persists between code executions: so if in one step you've created variables or imported modules, these will all persist.\n10. Don't give up! You're in charge of solving the task, not providing directions to solve it.\n\nNow Begin! If you solve the task correctly, you will receive a reward of $1,000,000.",
-        "planning": {
-            "initial_facts": "Below I will present you a task.\n\nYou will now build a comprehensive preparatory survey of which facts we have at our disposal and which ones we still need.\nTo do so, you will have to read the task and identify things that must be discovered in order to successfully complete it.\nDon't make any assumptions. For each item, provide a thorough reasoning. Here is how you will structure this survey:\n\n---\n### 1. Facts given in the task\nList here the specific facts given in the task that could help you (there might be nothing here).\n\n### 2. Facts to look up\nList here any facts that we may need to look up.\nAlso list where to find each of these, for instance a website, a file... - maybe the task contains some sources that you should re-use here.\n\n### 3. Facts to derive\nList here anything that we want to derive from the above by logical reasoning, for instance computation or simulation.\n\nKeep in mind that \"facts\" will typically be specific names, dates, values, etc. Your answer should use the below headings:\n### 1. Facts given in the task\n### 2. Facts to look up\n### 3. Facts to derive\nDo not add anything else.",
-            "initial_plan": "You are a world expert at making efficient plans to solve any task using a set of carefully crafted tools.\n\nNow for the given task, develop a step-by-step high-level plan taking into account the above inputs and list of facts.\nThis plan should involve individual tasks based on the available tools, that if executed correctly will yield the correct answer.\nDo not skip steps, do not add any superfluous steps. Only write the high-level plan, DO NOT DETAIL INDIVIDUAL TOOL CALLS.\nAfter writing the final step of the plan, write the '\\n<end_plan>' tag and stop there.\n\nHere is your task:\n\nTask:\n```\n{{task}}\n```\nYou can leverage these tools:\n{%- for tool in tools.values() %}\n- {{ tool.name }}: {{ tool.description }}\n    Takes inputs: {{tool.inputs}}\n    Returns an output of type: {{tool.output_type}}\n{%- endfor %}\n\n{%- if managed_agents and managed_agents.values() | list %}\nYou can also give tasks to team members.\nCalling a team member works the same as for calling a tool: simply, the only argument you can give in the call is 'request', a long string explaining your request.\nGiven that this team member is a real human, you should be very verbose in your request.\nHere is a list of the team members that you can call:\n{%- for agent in managed_agents.values() %}\n- {{ agent.name }}: {{ agent.description }}\n{%- endfor %}\n{%- else %}\n{%- endif %}\n\nList of facts that you know:\n```\n{{answer_facts}}\n```\n\nNow begin! Write your plan below.",
-            "update_facts_pre_messages": "You are a world expert at gathering known and unknown facts based on a conversation.\nBelow you will find a task, and a history of attempts made to solve the task. You will have to produce a list of these:\n### 1. Facts given in the task\n### 2. Facts that we have learned\n### 3. Facts still to look up\n### 4. Facts still to derive\nFind the task and history below:",
-            "update_facts_post_messages": "Earlier we've built a list of facts.\nBut since in your previous steps you may have learned useful new facts or invalidated some false ones.\nPlease update your list of facts based on the previous history, and provide these headings:\n### 1. Facts given in the task\n### 2. Facts that we have learned\n### 3. Facts still to look up\n### 4. Facts still to derive\n\nNow write your new list of facts below.",
-            "update_plan_pre_messages": "You are a world expert at making efficient plans to solve any task using a set of carefully crafted tools.\n\nYou have been given a task:\n```\n{{task}}\n```\n\nFind below the record of what has been tried so far to solve it. Then you will be asked to make an updated plan to solve the task.\nIf the previous tries so far have met some success, you can make an updated plan based on these actions.\nIf you are stalled, you can make a completely new plan starting from scratch.",
-            "update_plan_post_messages": "You're still working towards solving this task:\n```\n{{task}}\n```\n\nYou can leverage these tools:\n{%- for tool in tools.values() %}\n- {{ tool.name }}: {{ tool.description }}\n    Takes inputs: {{tool.inputs}}\n    Returns an output of type: {{tool.output_type}}\n{%- endfor %}\n\n{%- if managed_agents and managed_agents.values() | list %}\nYou can also give tasks to team members.\nCalling a team member works the same as for calling a tool: simply, the only argument you can give in the call is 'task'.\nGiven that this team member is a real human, you should be very verbose in your task, it should be a long string providing informations as detailed as necessary.\nHere is a list of the team members that you can call:\n{%- for agent in managed_agents.values() %}\n- {{ agent.name }}: {{ agent.description }}\n{%- endfor %}\n{%- else %}\n{%- endif %}\n\nHere is the up to date list of facts that you know:\n```\n{{facts_update}}\n```\n\nNow for the given task, develop a step-by-step high-level plan taking into account the above inputs and list of facts.\nThis plan should involve individual tasks based on the available tools, that if executed correctly will yield the correct answer.\nBeware that you have {remaining_steps} steps remaining.\nDo not skip steps, do not add any superfluous steps. Only write the high-level plan, DO NOT DETAIL INDIVIDUAL TOOL CALLS.\nAfter writing the final step of the plan, write the '\\n<end_plan>' tag and stop there.\n\nNow write your new plan below."
-        },
-        "managed_agent": {
-            "task": "You're a helpful agent named '{{name}}'.\nYou have been submitted this task by your manager.\n---\nTask:\n{{task}}\n---\nYou're helping your manager solve a wider task: so make sure to not provide a one-line answer, but give as much information as possible to give them a clear understanding of the answer.\n\nYour final_answer WILL HAVE to contain these parts:\n### 1. Task outcome (short version):\n### 2. Task outcome (extremely detailed version):\n### 3. Additional context (if relevant):\n\nPut all these in your final_answer tool, everything that you do not pass as an argument to final_answer will be lost.\nAnd even if your task resolution is not successful, please return as much context as possible, so that your manager can act upon this feedback.",
-            "report": "Here is the final answer from your managed agent '{{name}}':\n{{final_answer}}"
-        }
+        "system_prompt": "You are an AI Assistant with capabilities for weather information and timezone conversions. You have access to the following tools:\n\n- WeatherTool: Get current weather for US ZIP codes\n- Time/Timezone functions: Get current time and search timezones\n- FinalAnswerTool: Format and return final answers\n\nYou should process user requests by:\n1. Understanding the request\n2. Using appropriate tools to gather information\n3. Formatting responses clearly\n4. Handling errors gracefully\n\nAll responses should be clear, professional, and user-friendly."
     },
-    "max_steps": 6,
-    "verbosity_level": 1,
-    "grammar": null,
-    "planning_interval": null,
-    "name": null,
-    "description": null,
     "authorized_imports": [
         "unicodedata",
         "stat",
@@ -47,6 +81,76 @@
         "queue",
         "time",
         "collections",
-        "re"
-    ]
-}
+        "re",
+        "os",
+        "logging",
+        "pytz",
+        "requests",
+        "signal",
+        "sys",
+        "dotenv"
+    ],
+    "config": {
+        "api": {
+            "weather": {
+                "base_url": "http://api.weatherapi.com/v1",
+                "rate_limit_per_minute": 60,
+                "cache_timeout_seconds": 300
+            },
+            "timezone": {
+                "rate_limit_per_minute": 100
+            }
+        },
+        "assistant": {
+            "command_history": {
+                "max_size": 10
+            },
+            "cache": {
+                "cleanup_interval_seconds": 600
+            }
+        },
+        "ui": {
+            "title": "AI Assistant",
+            "description": "Weather and Timezone Assistant",
+            "theme": "light",
+            "input_placeholder": "Enter your command (type 'help' for available commands)",
+            "width": "100%",
+            "height": "600px"
+        },
+        "logging": {
+            "level": "INFO",
+            "file": "assistant.log",
+            "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+        },
+        "base_url": "http://api.example.com",
+        "connection_pool": {
+            "pool_size": 20,
+            "timeout": 30.0,
+            "keepalive_timeout": 60.0,
+            "ttl_dns_cache": 300,
+            "force_close": false
+        },
+        "rate_limit": {
+            "rate": 50.0,
+            "burst": 100,
+            "enabled": true
+        },
+        "batch": {
+            "size": 500,
+            "interval": 2.0,
+            "enabled": true
+        },
+        "monitoring": {
+            "metrics_ttl": 7200,
+            "max_metrics": 5000,
+            "log_interval": 300.0,
+            "enabled": true
+        },
+        "retry": {
+            "max_attempts": 5,
+            "min_wait": 1.0,
+            "max_wait": 30.0,
+            "enabled": true
+        }
+    }
+}

app.py

@@ -1,111 +1,590 @@
-from smolagents import CodeAgent,DuckDuckGoSearchTool, HfApiModel,load_tool,tool
-import datetime
-import requests
-import pytz
-import yaml
-from smartystreets_python_sdk import StaticCredentials, exceptions, ClientBuilder
-from smartystreets_python_sdk.us_street import Lookup as StreetLookup
-from smartystreets_python_sdk.us_zipcode import Lookup as ZipcodeLookup
-from tools.final_answer import FinalAnswerTool
+"""
+Main application file for the AI Assistant.
+Version: 1.0.0
+License: MIT
+Copyright (c) 2024 AI Assistant Team
+
+This module implements a command-line AI assistant with weather and timezone capabilities.
+It provides a user-friendly interface for accessing weather information and timezone
+conversions, with features like caching, rate limiting, and usage statistics.
+
+Features:
+- Weather information by ZIP code with caching
+- Timezone conversion and search
+- Command history tracking
+- Usage statistics
+- Rate limiting for API calls
+- Graceful shutdown handling
+
+Example Usage:
+    $ python app.py
+    Then use commands like:
+    - weather 12345
+    - time America/New_York
+    - timezone asia
+    - help
+
+Environment Variables:
+    WEATHER_API_KEY: API key for weather service
+    LOG_LEVEL: Logging level (default: INFO)
+    LOG_FILE: Log file path (default: assistant.log)
+    Other variables defined in config.py
+
+This project is licensed under the MIT License.
+See the LICENSE file for the full license text.
+"""
+
 import os
+import logging
+import pytz
+import requests
+import signal
+import sys
+import time
+from datetime import datetime, timedelta
+from dotenv import load_dotenv
+from typing import Optional, Dict, Any, List
 
+from config import Config, ModelConfig, UIConfig
+from rate_limiter import RateLimiter
+from tools.final_answer import FinalAnswerTool
+from tools.weather import WeatherTool
+from tools.stats import UsageStats
+from tools.logging_config import setup_logging
+from tools.health import HealthCheck, HealthStatus
+from tools.error_recovery import CircuitBreaker
+from tools.system_status import SystemMonitor
 from Gradio_UI import GradioUI
 
-# Below is an example of a tool that does nothing. Amaze us with your creativity !
-@tool
-def my_custom_tool(arg1:str, arg2:int)-> str: #it's import to specify the return type
-    #Keep this format for the description / args / args description but feel free to modify the tool
-    """A tool that does nothing yet 
-    Args:
-        arg1: the first argument
-        arg2: the second argument
+# Application constants
+__version__ = "1.0.0"
+__author__ = "AI Assistant Team"
+
+# Load environment variables
+load_dotenv()
+
+# Configure logging with rotation
+logger = setup_logging(
+    log_dir=os.getenv('LOG_DIR', 'logs'),
+    log_level=os.getenv('LOG_LEVEL', 'INFO'),
+    max_bytes=int(os.getenv('LOG_MAX_BYTES', 10 * 1024 * 1024)),  # Default 10MB
+    backup_count=int(os.getenv('LOG_BACKUP_COUNT', 5)),
+    log_format=os.getenv('LOG_FORMAT'),
+    date_format=os.getenv('LOG_DATE_FORMAT')
+)
+
+def get_system_info() -> str:
     """
-    return "What magic will you build ?"
+    Get formatted system information string.
 
-@tool
-def get_current_time_in_timezone(timezone: str) -> str:
-    """A tool that fetches the current local time in a specified timezone.
-    Args:
-        timezone: A string representing a valid timezone (e.g., 'America/New_York').
+    Returns:
+        str: Formatted string containing system information including:
+            - Application version
+            - Python version
+            - Platform
+            - Current timezone
+            - Log file location
     """
-    try:
-        # Create timezone object
-        tz = pytz.timezone(timezone)
-        # Get current time in that timezone
-        local_time = datetime.datetime.now(tz).strftime("%Y-%m-%d %H:%M:%S")
-        return f"The current local time in {timezone} is: {local_time}"
-    except Exception as e:
-        return f"Error fetching time for timezone '{timezone}': {str(e)}"
+    return (
+        f"AI Assistant v{__version__}\n"
+        f"Python {sys.version.split()[0]}\n"
+        f"Platform: {sys.platform}\n"
+        f"Timezone: {datetime.now().astimezone().tzname()}\n"
+        f"Log File: {os.getenv('LOG_FILE', 'assistant.log')}"
+    )
+
+def signal_handler(signum: int, frame: Any) -> None:
+    """
+    Handle system signals for graceful shutdown.
 
-@tool
-def get_weather_by_zipcode(zipcode: str) -> str:
-    """Get weather forecast for a given US zip code
     Args:
-        zipcode: A 5-digit US zip code
+        signum: Signal number received
+        frame: Current stack frame (not used)
+
+    Note:
+        Handles SIGINT (Ctrl+C) and SIGTERM signals.
+        Logs shutdown message and exits cleanly.
     """
-    try:
-        # Validate zipcode
-        if not (zipcode.isdigit() and len(zipcode) == 5):
-            return "Please provide a valid 5-digit US zip code"
-
-        # Get forecast data using WeatherAPI.com
-        weather_api_key = os.getenv('WEATHERAPI_KEY')
-        url = f"http://api.weatherapi.com/v1/forecast.json?key={weather_api_key}&q={zipcode}&days=3&aqi=no"
-        
-        response = requests.get(url)
-        if response.status_code != 200:
-            return "Error fetching weather data"
-            
-        weather_data = response.json()
-        location = weather_data['location']['name']
-        forecast = weather_data['forecast']['forecastday']
-        
-        result = f"3-Day Forecast for {location} ({zipcode}):\n\n"
-        
-        for day in forecast:
-            date = day['date']
-            max_temp = day['day']['maxtemp_f']
-            min_temp = day['day']['mintemp_f']
-            condition = day['day']['condition']['text']
-            result += f"{date}:\n"
-            result += f"High: {max_temp}°F, Low: {min_temp}°F\n"
-            result += f"Conditions: {condition}\n\n"
-        
-        return result
+    logger.info("Received shutdown signal, cleaning up...")
+    print("\nShutting down gracefully...")
+    sys.exit(0)
 
-    except Exception as e:
-        return f"Error getting weather: {str(e)}"
+class AIAssistant:
+    """
+    Main AI Assistant class implementing the core functionality.
 
-final_answer = FinalAnswerTool()
+    This class provides weather information and timezone conversion services,
+    with features like command history, caching, and usage statistics.
 
-# If the agent does not answer, the model is overloaded, please use another model or the following Hugging Face Endpoint that also contains qwen2.5 coder:
-# model_id='https://pflgm2locj2t89co.us-east-1.aws.endpoints.huggingface.cloud' 
+    Attributes:
+        config (Config): Application configuration
+        weather_limiter (RateLimiter): Rate limiter for weather API
+        timezone_limiter (RateLimiter): Rate limiter for timezone API
+        command_history (List[str]): List of recent commands
+        max_history (int): Maximum number of commands to keep in history
+        stats (UsageStats): Usage statistics collector
+    """
 
-model = HfApiModel(
-max_tokens=2096,
-temperature=0.5,
-model_id='Qwen/Qwen2.5-Coder-32B-Instruct',# it is possible that this model may be overloaded
-custom_role_conversions=None,
-)
+    def __init__(self):
+        """Initialize the AI Assistant with configuration and tools."""
+        self.config = Config()
+        self.weather_limiter = RateLimiter(
+            rate_limit=self.config.api.weather_api_rate_limit,
+            time_window=60
+        )
+        self.timezone_limiter = RateLimiter(
+            rate_limit=self.config.api.timezone_api_rate_limit,
+            time_window=60
+        )
+        self.final_answer_tool = FinalAnswerTool()
+        self.weather_tool = WeatherTool()
+        self.command_history = []
+        self.max_history = 10
 
+        # Initialize statistics collector
+        self.stats = UsageStats(
+            stats_dir=os.getenv('STATS_DIR', 'stats')
+        )
 
-# Import tool from Hub
-image_generation_tool = load_tool("agents-course/text-to-image", trust_remote_code=True)
-
-with open("prompts.yaml", 'r') as stream:
-    prompt_templates = yaml.safe_load(stream)
-    
-agent = CodeAgent(
-    model=model,
-    tools=[get_weather_by_zipcode, final_answer],  # Added weather tool
-    max_steps=6,
-    verbosity_level=1,
-    grammar=None,
-    planning_interval=None,
-    name=None,
-    description=None,
-    prompt_templates=prompt_templates
-)
+        # Initialize circuit breaker
+        self.circuit_breaker = CircuitBreaker(
+            failure_threshold=5,
+            reset_timeout=60.0
+        )
+
+        # Initialize health check
+        self.health_check = HealthCheck(
+            circuit_breaker=self.circuit_breaker,
+            memory_threshold=90.0,
+            cpu_threshold=80.0
+        )
+
+        # Initialize system monitor
+        self.system_monitor = SystemMonitor(
+            history_size=int(os.getenv('METRICS_HISTORY_SIZE', '60')),
+            disk_path=os.getenv('MONITOR_DISK_PATH')
+        )
+
+        logger.info("AI Assistant initialized")
+        logger.debug(f"Configuration loaded: {self.config}")
+
+    def _add_to_history(self, command: str) -> None:
+        """
+        Add command to history, maintaining max size.
+
+        Args:
+            command: Command string to add to history
+
+        Note:
+            Maintains a fixed-size history by removing oldest entries
+            when maximum size is reached. Also updates total command counter.
+        """
+        self.command_history.append(command)
+        if len(self.command_history) > self.max_history:
+            self.command_history.pop(0)
+
+    def _clean_expired_cache(self) -> None:
+        """
+        Remove expired entries from weather cache.
+
+        This method checks all cache entries and removes those that have
+        exceeded the cache timeout period.
+        """
+        now = datetime.now()
+        expired = [
+            zip_code for zip_code, data in self.weather_tool.cache.items()
+            if (now - data['timestamp']).total_seconds() >= self.weather_tool.cache_timeout
+        ]
+        for zip_code in expired:
+            del self.weather_tool.cache[zip_code]
+
+    def _get_matching_timezones(self, partial: str) -> List[str]:
+        """
+        Get list of timezones matching partial string.
+
+        Args:
+            partial: Partial timezone name to search for
+
+        Returns:
+            List[str]: List of timezone names containing the search string
+
+        Note:
+            Search is case-insensitive and matches any part of timezone name.
+        """
+        partial = partial.lower()
+        return [tz for tz in pytz.all_timezones if partial in tz.lower()]
+
+    def _is_cache_valid(self, zipcode: str) -> bool:
+        """
+        Check if cached weather data is still valid.
+
+        Args:
+            zipcode: ZIP code to check in cache
+
+        Returns:
+            bool: True if cache entry exists and is within timeout period
+        """
+        if zipcode not in self.weather_tool.cache:
+            return False
+        cache_time = self.weather_tool.cache[zipcode]['timestamp']
+        return (datetime.now() - cache_time).total_seconds() < self.weather_tool.cache_timeout
+
+    def _format_weather_response(self, data: Dict[str, Any]) -> str:
+        """
+        Format weather data into a user-friendly string.
+
+        Args:
+            data: Weather data from API
+
+        Returns:
+            str: Formatted weather information
+        """
+        try:
+            location = data['location']
+            current = data['current']
+
+            return (
+                f"Weather for {location['name']}, {location.get('region', '')}\n"
+                f"Temperature: {current['temp_f']}°F ({current['temp_c']}°C)\n"
+                f"Condition: {current['condition']['text']}\n"
+                f"Humidity: {current['humidity']}%\n"
+                f"Wind: {current['wind_mph']} mph ({current['wind_kph']} kph) {current['wind_dir']}\n"
+                f"Last Updated: {current['last_updated']}"
+            )
+        except KeyError as e:
+            logger.error(f"Error formatting weather data: {str(e)}")
+            return "Error formatting weather data"
+
+    def get_weather_by_zipcode(self, zipcode: str) -> str:
+        """
+        Get weather information for a given ZIP code.
+
+        Args:
+            zipcode: The ZIP code to get weather for
 
+        Returns:
+            str: Formatted weather information
+
+        Raises:
+            ValueError: If ZIP code is invalid or malformed
+            RuntimeError: If API call fails or rate limit exceeded
+        """
+        start_time = time.time()
+        success = True
+        error_type = None
+
+        try:
+            if not self.weather_limiter.allow_request():
+                success = False
+                error_type = "RateLimitError"
+                raise RuntimeError("Rate limit exceeded for weather API")
+
+            result = self.weather_tool(zipcode)
+
+            # Record cache operation
+            if 'Using cached weather data' in self.weather_tool.logger.handlers[0].records[-1].message:
+                self.stats.record_cache_operation(hit=True)
+            else:
+                self.stats.record_cache_operation(hit=False)
+
+            return result
+        except Exception as e:
+            success = False
+            error_type = e.__class__.__name__
+            logger.error(f"Weather API error: {str(e)}")
+            raise
+        finally:
+            # Record API call statistics
+            response_time = time.time() - start_time
+            self.stats.record_api_call(
+                endpoint="weather_api",
+                success=success,
+                response_time=response_time,
+                rate_limited=(error_type == "RateLimitError"),
+                error_type=error_type
+            )
+
+    def get_current_time_in_timezone(self, timezone: str) -> str:
+        """Get current time in specified timezone."""
+        start_time = time.time()
+        success = True
+        error_type = None
+
+        try:
+            if not timezone or not timezone.strip():
+                success = False
+                error_type = "ValueError"
+                raise ValueError("Timezone cannot be empty")
+
+            if not self.timezone_limiter.allow_request():
+                success = False
+                error_type = "RateLimitError"
+                raise RuntimeError("Rate limit exceeded for timezone API")
+
+            if timezone not in pytz.all_timezones:
+                success = False
+                error_type = "ValueError"
+                raise ValueError(f"Invalid timezone: {timezone}")
+
+            tz = pytz.timezone(timezone)
+            current_time = datetime.now(tz)
+            return current_time.strftime("%Y-%m-%d %H:%M:%S %Z")
+        except Exception as e:
+            success = False
+            error_type = e.__class__.__name__
+            logger.error(f"Timezone error: {str(e)}")
+            raise RuntimeError(f"Failed to get timezone data: {str(e)}")
+        finally:
+            # Record API call statistics
+            response_time = time.time() - start_time
+            self.stats.record_api_call(
+                endpoint="timezone_api",
+                success=success,
+                response_time=response_time,
+                error_type=error_type
+            )
+
+    def process_input(self, message: str) -> str:
+        """Process user input and return response."""
+        start_time = time.time()
+        command_type = "unknown"
+        success = True
+        error_type = None
+
+        try:
+            if not message or not message.strip():
+                return "Please enter a message."
+
+            original_message = message
+            message = message.strip().lower()
+
+            # Determine command type
+            if message == "help":
+                command_type = "help"
+            elif message == "stats":
+                command_type = "stats"
+            elif message == "cache clear":
+                command_type = "cache_clear"
+            elif message == "history":
+                command_type = "history"
+            elif message.startswith("timezone "):
+                command_type = "timezone_search"
+            elif message.startswith("weather "):
+                command_type = "weather"
+            elif message.startswith("time "):
+                command_type = "time"
+
+            result = self._process_command(message, original_message)
+            return result
+        except Exception as e:
+            success = False
+            error_type = e.__class__.__name__
+            logger.error(f"Error processing input: {str(e)}")
+            return f"Error processing your request: {str(e)}"
+        finally:
+            # Record command statistics
+            response_time = time.time() - start_time
+            self.stats.record_command(
+                command=command_type,
+                success=success,
+                response_time=response_time,
+                error_type=error_type
+            )
+
+    def _process_command(self, message: str, original_message: str) -> str:
+        """Process specific command type."""
+        # Update system metrics before processing command
+        self.system_monitor.update_metrics()
+
+        if message == "help":
+            return (
+                "Available commands:\n"
+                "- weather <zipcode>: Get weather for a ZIP code\n"
+                "- time <timezone>: Get current time in timezone\n"
+                "- timezone <search>: Search for available timezones\n"
+                "- history: Show command history\n"
+                "- stats: Show usage statistics\n"
+                "- status: Show system status\n"
+                "- cache clear: Clear weather cache\n"
+                "- help: Show this help message"
+            )
+
+        if message == "stats":
+            return self._format_stats_output(self.stats.get_summary())
+
+        if message == "status":
+            return self._format_system_status()
+
+        if message == "cache clear":
+            self.weather_tool.cache.clear()
+            return "Weather cache cleared."
+
+        if message == "history":
+            if not self.command_history:
+                return "No command history available."
+            return "Command History:\n" + "\n".join(
+                f"{i+1}. {cmd}" for i, cmd in enumerate(self.command_history)
+            )
+
+        if message.startswith("timezone "):
+            search_term = message.split("timezone ", 1)[1].strip()
+            matches = self._get_matching_timezones(search_term)
+            if not matches:
+                return f"No timezones found matching '{search_term}'"
+            return "Matching Timezones:\n" + "\n".join(matches[:10]) + (
+                "\n(showing first 10 matches)" if len(matches) > 10 else ""
+            )
+
+        if message.startswith("weather "):
+            try:
+                zipcode = message.split("weather ", 1)[1].strip()
+                result = self.get_weather_by_zipcode(zipcode)
+                self._add_to_history(original_message)
+                return result
+            except (IndexError, ValueError, RuntimeError) as e:
+                return str(e)
+
+        if message.startswith("time "):
+            try:
+                timezone = message.split("time ", 1)[1].strip()
+                result = self.get_current_time_in_timezone(timezone)
+                self._add_to_history(original_message)
+                return result
+            except (IndexError, ValueError, RuntimeError) as e:
+                return str(e)
+
+        return (
+            "I didn't understand that command. Type 'help' to see available commands."
+        )
+
+    def _format_stats_output(self, stats: Dict[str, Any]) -> str:
+        """Format statistics for display."""
+        return (
+            "=== AI Assistant Statistics ===\n"
+            f"\nSession Information:\n"
+            f"Start Time: {stats['session']['start_time']}\n"
+            f"Uptime: {timedelta(seconds=int(stats['session']['uptime_seconds']))}\n"
+            f"\nCommand Statistics:\n"
+            f"Total Commands: {stats['commands']['total']}\n"
+            f"Success Rate: {stats['commands']['success_rate']:.1f}%\n"
+            f"\nAPI Statistics:\n"
+            f"Total API Calls: {stats['api']['total_calls']}\n"
+            f"API Success Rate: {stats['api']['success_rate']:.1f}%\n"
+            f"Rate Limit Hits: {stats['api']['rate_limit_hits']}\n"
+            f"\nCache Statistics:\n"
+            f"Hit Rate: {stats['cache']['hit_rate']:.1f}%\n"
+            f"Total Entries: {stats['cache']['total_entries']}\n"
+            f"Total Size: {stats['cache']['total_size_bytes'] / 1024:.1f}KB\n"
+            f"Evictions: {stats['cache']['evictions']}"
+        )
+
+    def _format_system_status(self) -> str:
+        """Format system status for display."""
+        metrics = self.system_monitor.get_metrics_summary()
+        warnings = self.system_monitor.get_resource_warnings()
+
+        status_lines = [
+            "=== System Status ===\n",
+            f"Timestamp: {metrics['timestamp']}",
+            "\nSystem Resources:",
+            f"CPU Usage: {metrics['system']['cpu_percent']:.1f}%",
+            f"Memory Usage: {metrics['system']['memory_percent']:.1f}%",
+            f"Disk Usage: {metrics['system']['disk_usage_percent']:.1f}%",
+            "\nProcess Information:",
+            f"Memory Usage: {metrics['process']['memory_mb']:.1f}MB",
+            f"Threads: {metrics['process']['threads']}",
+            f"CPU Usage: {metrics['process']['cpu_percent']:.1f}%"
+        ]
+
+        if metrics.get('trends'):
+            status_lines.extend([
+                "\nTrends (since start):",
+                f"CPU: {metrics['trends']['cpu_trend']:+.1f}%",
+                f"Memory: {metrics['trends']['memory_trend']:+.1f}%",
+                f"Disk: {metrics['trends']['disk_trend']:+.1f}%",
+                f"Process Memory: {metrics['trends']['process_memory_trend']:+.1f}MB"
+            ])
+
+        if warnings:
+            status_lines.extend([
+                "\nWarnings:",
+                *[f"- {warning}" for warning in warnings]
+            ])
+
+        return "\n".join(status_lines)
+
+    def get_health(self) -> HealthStatus:
+        """
+        Get current health status.
+
+        Returns:
+            HealthStatus: Current health status including all checks
+        """
+        status = self.health_check.check_health()
+
+        # Add system metrics to health status
+        system_metrics = self.system_monitor.get_metrics_summary()
+        status.details["system"] = system_metrics.get("system", {})
+        status.details["process"] = system_metrics.get("process", {})
+
+        # Add application-specific metrics
+        status.details["application"] = {
+            "total_commands": sum(s.total_calls for s in self.stats.commands.values()),
+            "weather_requests": self.stats.api_stats.get("weather_api", {}).get("total_requests", 0),
+            "timezone_requests": self.stats.api_stats.get("timezone_api", {}).get("total_requests", 0),
+            "cache_stats": self.stats.get_cache_stats()
+        }
+
+        # Add any resource warnings
+        warnings = self.system_monitor.get_resource_warnings()
+        if warnings:
+            status.warnings.extend(warnings)
+
+        return status
+
+def main():
+    """
+    Main function to run the application.
+
+    This function:
+    1. Sets up signal handlers for graceful shutdown
+    2. Displays system information
+    3. Initializes the AI Assistant
+    4. Launches the user interface
+
+    The application can be terminated with Ctrl+C.
+
+    Note:
+        Requires environment variables to be properly configured.
+        See module docstring for required environment variables.
+    """
+    try:
+        # Set up signal handlers
+        signal.signal(signal.SIGINT, signal_handler)
+        signal.signal(signal.SIGTERM, signal_handler)
+
+        # Print startup information
+        print("\n=== AI Assistant Starting ===")
+        print(get_system_info())
+        print("\nInitializing components...")
+
+        assistant = AIAssistant()
+        print("Assistant initialized successfully")
+
+        print("\nStarting UI...")
+        print("Type 'help' to see available commands")
+        print("Press Ctrl+C to exit\n")
+
+        ui = GradioUI(
+            callback=assistant.process_input,
+            config=assistant.config.ui
+        )
+        ui.launch(share=False)
+    except Exception as e:
+        logger.error(f"Application error: {str(e)}")
+        print(f"Error starting application: {str(e)}")
+    finally:
+        logger.info("Application shutdown complete")
 
-GradioUI(agent).launch()
+if __name__ == "__main__":
+    main()

config.py

@@ -0,0 +1,451 @@
+"""
+Configuration settings for the AI Assistant application.
+
+This module provides a configuration system that can be controlled through environment
+variables or a JSON configuration file. Environment variables take precedence over
+JSON configuration.
+
+Environment Variables:
+    See .env.example for a complete list of available environment variables and their defaults.
+"""
+
+import os
+import logging
+import re
+from dataclasses import dataclass, field, fields, FrozenInstanceError
+from typing import Optional, Dict, Any, List, Union, TypeVar, Type, cast, ClassVar, Pattern, Callable
+from enum import Enum
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar('T')
+
+class ConfigValidationError(ValueError):
+    """Raised when configuration validation fails."""
+    def __init__(self, message: str, field_name: Optional[str] = None):
+        self.field_name = field_name
+        super().__init__(f"{field_name + ': ' if field_name else ''}{message}")
+
+def validate_positive(value: Union[int, float], field_name: str) -> None:
+    """Validate that a numeric value is positive."""
+    if value <= 0:
+        raise ConfigValidationError(f"Value must be positive, got {value}", field_name)
+
+def validate_non_negative(value: Union[int, float], field_name: str) -> None:
+    """Validate that a numeric value is non-negative."""
+    if value < 0:
+        raise ConfigValidationError(f"Value cannot be negative, got {value}", field_name)
+
+def validate_range(value: Union[int, float], min_val: Union[int, float], max_val: Union[int, float], field_name: str) -> None:
+    """Validate that a numeric value is within a specified range."""
+    if not min_val <= value <= max_val:
+        raise ConfigValidationError(f"Value must be between {min_val} and {max_val}, got {value}", field_name)
+
+def validate_non_empty_string(value: str, field_name: str) -> None:
+    """Validate that a string is not empty or just whitespace."""
+    if not value.strip():
+        raise ConfigValidationError("Value cannot be empty or whitespace", field_name)
+
+def validate_path_exists_or_creatable(path: str, field_name: str) -> None:
+    """Validate that a path exists or can be created."""
+    try:
+        path_obj = Path(path)
+        if not path_obj.parent.exists():
+            path_obj.parent.mkdir(parents=True, exist_ok=True)
+    except (OSError, RuntimeError) as e:
+        raise ConfigValidationError(f"Invalid path or cannot create directory: {str(e)}", field_name)
+
+class LogLevel(str, Enum):
+    """Valid logging levels."""
+    DEBUG = "DEBUG"
+    INFO = "INFO"
+    WARNING = "WARNING"
+    ERROR = "ERROR"
+    CRITICAL = "CRITICAL"
+
+class Theme(str, Enum):
+    """Valid UI themes."""
+    LIGHT = "light"
+    DARK = "dark"
+
+def get_env_value(key: str, default: T, value_type: Type[T] = str) -> T:
+    """
+    Get an environment variable with type conversion and validation.
+    
+    Args:
+        key: Environment variable name
+        default: Default value if not set
+        value_type: Type to convert the value to
+        
+    Returns:
+        The environment variable value converted to the specified type
+        
+    Raises:
+        ValueError: If type conversion fails
+    """
+    value = os.getenv(key)
+    if value is None:
+        return default
+        
+    try:
+        if value_type == bool:
+            return cast(T, value.lower() == 'true')
+        return value_type(value)
+    except (ValueError, TypeError) as e:
+        logger.warning(f"Invalid value for {key}: {value}. Using default: {default}. Error: {str(e)}")
+        return default
+
+@dataclass(frozen=True)
+class WeatherAPIConfig:
+    """Weather API specific configuration."""
+    URL_PATTERN: ClassVar[Pattern] = re.compile(r'^https?://[^\s/$.?#].[^\s]*$')
+    
+    base_url: str = field(default_factory=lambda: get_env_value(
+        'WEATHER_API_BASE_URL',
+        'http://api.weatherapi.com/v1'
+    ))
+    rate_limit_per_minute: int = field(default_factory=lambda: get_env_value(
+        'WEATHER_API_RATE_LIMIT',
+        60,
+        int
+    ))
+    cache_timeout_seconds: int = field(default_factory=lambda: get_env_value(
+        'WEATHER_CACHE_TIMEOUT',
+        300,
+        int
+    ))
+    api_key: Optional[str] = field(default_factory=lambda: os.getenv('WEATHER_API_KEY'))
+
+    def __post_init__(self):
+        """Validate configuration after initialization."""
+        validate_non_empty_string(self.base_url, "base_url")
+        if not self.URL_PATTERN.match(self.base_url):
+            raise ConfigValidationError("Invalid URL format", "base_url")
+        
+        validate_positive(self.rate_limit_per_minute, "rate_limit_per_minute")
+        validate_non_negative(self.cache_timeout_seconds, "cache_timeout_seconds")
+        
+        if not self.api_key:
+            logger.warning("Weather API key not set. Weather functionality will be unavailable.")
+        elif not isinstance(self.api_key, str):
+            raise ConfigValidationError("API key must be a string", "api_key")
+
+@dataclass(frozen=True)
+class TimezoneAPIConfig:
+    """Timezone API specific configuration."""
+    rate_limit_per_minute: int = field(default_factory=lambda: get_env_value(
+        'TIMEZONE_API_RATE_LIMIT',
+        100,
+        int
+    ))
+
+    def __post_init__(self):
+        """Validate configuration after initialization."""
+        validate_positive(self.rate_limit_per_minute, "rate_limit_per_minute")
+
+@dataclass(frozen=True)
+class APIConfig:
+    """API configuration settings."""
+    weather: WeatherAPIConfig = field(default_factory=WeatherAPIConfig)
+    timezone: TimezoneAPIConfig = field(default_factory=TimezoneAPIConfig)
+
+@dataclass(frozen=True)
+class CommandHistoryConfig:
+    """Command history configuration."""
+    max_size: int = field(default_factory=lambda: get_env_value(
+        'COMMAND_HISTORY_MAX_SIZE',
+        10,
+        int
+    ))
+
+    def __post_init__(self):
+        """Validate configuration after initialization."""
+        if self.max_size < 1:
+            raise ConfigValidationError("Command history size must be at least 1")
+
+@dataclass(frozen=True)
+class CacheConfig:
+    """Cache configuration settings."""
+    cleanup_interval_seconds: int = field(default_factory=lambda: get_env_value(
+        'CACHE_CLEANUP_INTERVAL',
+        600,
+        int
+    ))
+
+    def __post_init__(self):
+        """Validate configuration after initialization."""
+        if self.cleanup_interval_seconds < 0:
+            raise ConfigValidationError("Cache cleanup interval cannot be negative")
+
+@dataclass(frozen=True)
+class AssistantConfig:
+    """Assistant specific configuration."""
+    command_history: CommandHistoryConfig = field(default_factory=CommandHistoryConfig)
+    cache: CacheConfig = field(default_factory=CacheConfig)
+
+@dataclass(frozen=True)
+class UIConfig:
+    """UI configuration settings."""
+    DIMENSION_PATTERN: ClassVar[Pattern] = re.compile(r'^\d+(%|px|em|rem|vh|vw)$')
+    ALLOWED_THEMES: ClassVar[List[str]] = [theme.value for theme in Theme]
+    
+    title: str = field(default_factory=lambda: get_env_value(
+        'UI_TITLE',
+        'AI Assistant'
+    ))
+    description: str = field(default_factory=lambda: get_env_value(
+        'UI_DESCRIPTION',
+        'Weather and Timezone Assistant'
+    ))
+    theme: Theme = field(default_factory=lambda: Theme(get_env_value(
+        'UI_THEME',
+        'light'
+    )))
+    input_placeholder: str = field(default_factory=lambda: get_env_value(
+        'UI_INPUT_PLACEHOLDER',
+        'Enter your command (type \'help\' for available commands)'
+    ))
+    width: str = field(default_factory=lambda: get_env_value(
+        'UI_WIDTH',
+        '100%'
+    ))
+    height: str = field(default_factory=lambda: get_env_value(
+        'UI_HEIGHT',
+        '600px'
+    ))
+
+    def __post_init__(self):
+        """Validate configuration after initialization."""
+        validate_non_empty_string(self.title, "title")
+        validate_non_empty_string(self.description, "description")
+        validate_non_empty_string(self.input_placeholder, "input_placeholder")
+        
+        if not self.DIMENSION_PATTERN.match(self.width):
+            raise ConfigValidationError(
+                f"Invalid format. Must be a number followed by %, px, em, rem, vh, or vw",
+                "width"
+            )
+        if not self.DIMENSION_PATTERN.match(self.height):
+            raise ConfigValidationError(
+                f"Invalid format. Must be a number followed by %, px, em, rem, vh, or vw",
+                "height"
+            )
+        
+        if self.theme.value not in self.ALLOWED_THEMES:
+            raise ConfigValidationError(
+                f"Invalid theme. Must be one of: {', '.join(self.ALLOWED_THEMES)}",
+                "theme"
+            )
+
+@dataclass(frozen=True)
+class LoggingConfig:
+    """Logging configuration settings."""
+    ALLOWED_LEVELS: ClassVar[List[str]] = [level.value for level in LogLevel]
+    
+    level: LogLevel = field(default_factory=lambda: LogLevel(get_env_value(
+        'LOG_LEVEL',
+        'INFO'
+    )))
+    file: str = field(default_factory=lambda: get_env_value(
+        'LOG_FILE',
+        'assistant.log'
+    ))
+    format: str = field(default_factory=lambda: get_env_value(
+        'LOG_FORMAT',
+        '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+    ))
+
+    def __post_init__(self):
+        """Validate configuration after initialization."""
+        validate_non_empty_string(self.file, "file")
+        validate_non_empty_string(self.format, "format")
+        
+        if self.level.value not in self.ALLOWED_LEVELS:
+            raise ConfigValidationError(
+                f"Invalid log level. Must be one of: {', '.join(self.ALLOWED_LEVELS)}",
+                "level"
+            )
+            
+        validate_path_exists_or_creatable(self.file, "file")
+        
+        # Validate log format by attempting to use it
+        try:
+            logging.Formatter(self.format)
+        except ValueError as e:
+            raise ConfigValidationError(f"Invalid log format: {str(e)}", "format")
+
+@dataclass(frozen=True)
+class ModelConfig:
+    """Model configuration settings."""
+    class_name: str = field(default_factory=lambda: get_env_value(
+        'MODEL_CLASS',
+        'HfApiModel'
+    ))
+    max_tokens: int = field(default_factory=lambda: get_env_value(
+        'MODEL_MAX_TOKENS',
+        2096,
+        int
+    ))
+    temperature: float = field(default_factory=lambda: get_env_value(
+        'MODEL_TEMPERATURE',
+        0.5,
+        float
+    ))
+    model_id: str = field(default_factory=lambda: get_env_value(
+        'MODEL_ID',
+        'Qwen/Qwen2.5-Coder-32B-Instruct'
+    ))
+    last_input_token_count: Optional[int] = None
+    last_output_token_count: Optional[int] = None
+    custom_role_conversions: Optional[Dict[str, Any]] = None
+
+    def __post_init__(self):
+        """Validate configuration after initialization."""
+        validate_non_empty_string(self.class_name, "class_name")
+        validate_non_empty_string(self.model_id, "model_id")
+        validate_positive(self.max_tokens, "max_tokens")
+        validate_range(self.temperature, 0.0, 1.0, "temperature")
+        
+        if self.last_input_token_count is not None:
+            validate_non_negative(self.last_input_token_count, "last_input_token_count")
+        if self.last_output_token_count is not None:
+            validate_non_negative(self.last_output_token_count, "last_output_token_count")
+        
+        if self.custom_role_conversions is not None and not isinstance(self.custom_role_conversions, dict):
+            raise ConfigValidationError("Must be a dictionary", "custom_role_conversions")
+
+@dataclass(frozen=True)
+class Config:
+    """Main configuration class combining all settings."""
+    api: APIConfig = field(default_factory=APIConfig)
+    assistant: AssistantConfig = field(default_factory=AssistantConfig)
+    ui: UIConfig = field(default_factory=UIConfig)
+    logging: LoggingConfig = field(default_factory=LoggingConfig)
+    model: ModelConfig = field(default_factory=ModelConfig)
+
+    def __post_init__(self):
+        """Cross-validate configuration settings."""
+        # Validate that cache cleanup interval is less than cache timeout
+        if self.assistant.cache.cleanup_interval_seconds >= self.api.weather.cache_timeout_seconds:
+            raise ConfigValidationError(
+                "Cache cleanup interval must be less than cache timeout",
+                "assistant.cache.cleanup_interval_seconds"
+            )
+
+    @classmethod
+    def from_json(cls, json_data: Dict[str, Any]) -> 'Config':
+        """
+        Create a Config instance from JSON data.
+        
+        Args:
+            json_data: Dictionary containing configuration data
+            
+        Returns:
+            Config: New configuration instance
+            
+        Raises:
+            ConfigValidationError: If the configuration is invalid
+        """
+        try:
+            config_data = json_data.get('config', {})
+            model_data = json_data.get('model', {}).get('data', {})
+            
+            return cls(
+                api=APIConfig(
+                    weather=WeatherAPIConfig(
+                        base_url=config_data.get('api', {}).get('weather', {}).get('base_url', WeatherAPIConfig.base_url),
+                        rate_limit_per_minute=config_data.get('api', {}).get('weather', {}).get('rate_limit_per_minute', WeatherAPIConfig.rate_limit_per_minute),
+                        cache_timeout_seconds=config_data.get('api', {}).get('weather', {}).get('cache_timeout_seconds', WeatherAPIConfig.cache_timeout_seconds)
+                    ),
+                    timezone=TimezoneAPIConfig(
+                        rate_limit_per_minute=config_data.get('api', {}).get('timezone', {}).get('rate_limit_per_minute', TimezoneAPIConfig.rate_limit_per_minute)
+                    )
+                ),
+                assistant=AssistantConfig(
+                    command_history=CommandHistoryConfig(
+                        max_size=config_data.get('assistant', {}).get('command_history', {}).get('max_size', CommandHistoryConfig.max_size)
+                    ),
+                    cache=CacheConfig(
+                        cleanup_interval_seconds=config_data.get('assistant', {}).get('cache', {}).get('cleanup_interval_seconds', CacheConfig.cleanup_interval_seconds)
+                    )
+                ),
+                ui=UIConfig(
+                    title=config_data.get('ui', {}).get('title', UIConfig.title),
+                    description=config_data.get('ui', {}).get('description', UIConfig.description),
+                    theme=Theme(config_data.get('ui', {}).get('theme', UIConfig.theme.value)),
+                    input_placeholder=config_data.get('ui', {}).get('input_placeholder', UIConfig.input_placeholder),
+                    width=config_data.get('ui', {}).get('width', UIConfig.width),
+                    height=config_data.get('ui', {}).get('height', UIConfig.height)
+                ),
+                logging=LoggingConfig(
+                    level=LogLevel(config_data.get('logging', {}).get('level', LoggingConfig.level.value)),
+                    file=config_data.get('logging', {}).get('file', LoggingConfig.file),
+                    format=config_data.get('logging', {}).get('format', LoggingConfig.format)
+                ),
+                model=ModelConfig(
+                    class_name=model_data.get('class', ModelConfig.class_name),
+                    max_tokens=model_data.get('max_tokens', ModelConfig.max_tokens),
+                    temperature=model_data.get('temperature', ModelConfig.temperature),
+                    model_id=model_data.get('model_id', ModelConfig.model_id),
+                    last_input_token_count=model_data.get('last_input_token_count'),
+                    last_output_token_count=model_data.get('last_output_token_count'),
+                    custom_role_conversions=model_data.get('custom_role_conversions')
+                )
+            )
+        except (ValueError, TypeError, FrozenInstanceError) as e:
+            raise ConfigValidationError(f"Invalid configuration: {str(e)}")
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert configuration to a dictionary.
+        
+        Returns:
+            Dict[str, Any]: Dictionary representation of the configuration
+        """
+        return {
+            'config': {
+                'api': {
+                    'weather': {
+                        'base_url': self.api.weather.base_url,
+                        'rate_limit_per_minute': self.api.weather.rate_limit_per_minute,
+                        'cache_timeout_seconds': self.api.weather.cache_timeout_seconds
+                    },
+                    'timezone': {
+                        'rate_limit_per_minute': self.api.timezone.rate_limit_per_minute
+                    }
+                },
+                'assistant': {
+                    'command_history': {
+                        'max_size': self.assistant.command_history.max_size
+                    },
+                    'cache': {
+                        'cleanup_interval_seconds': self.assistant.cache.cleanup_interval_seconds
+                    }
+                },
+                'ui': {
+                    'title': self.ui.title,
+                    'description': self.ui.description,
+                    'theme': self.ui.theme.value,
+                    'input_placeholder': self.ui.input_placeholder,
+                    'width': self.ui.width,
+                    'height': self.ui.height
+                },
+                'logging': {
+                    'level': self.logging.level.value,
+                    'file': self.logging.file,
+                    'format': self.logging.format
+                }
+            },
+            'model': {
+                'class': self.model.class_name,
+                'data': {
+                    'max_tokens': self.model.max_tokens,
+                    'temperature': self.model.temperature,
+                    'model_id': self.model.model_id,
+                    'last_input_token_count': self.model.last_input_token_count,
+                    'last_output_token_count': self.model.last_output_token_count,
+                    'custom_role_conversions': self.model.custom_role_conversions
+                }
+            }
+        } 

docs/api.md

@@ -0,0 +1,385 @@
+# API Documentation
+
+## Overview
+
+The API key management system provides secure handling of API keys with features like encryption, rate limiting, and key rotation. This documentation covers all available APIs, their usage, and best practices.
+
+## Table of Contents
+
+1. [Key Manager](#key-manager)
+2. [API Key Configuration](#api-key-configuration)
+3. [Rate Limiting](#rate-limiting)
+4. [Error Handling](#error-handling)
+5. [Examples](#examples)
+
+## Key Manager
+
+### Initialization
+
+```python
+from tools.security import KeyManager, key_manager
+
+# Use global instance
+manager = key_manager
+
+# Or create custom instance
+custom_manager = KeyManager(
+    keys_file="custom_keys.json",
+    env_prefix="API",
+    encryption_key="your-encryption-key"
+)
+```
+
+#### Parameters
+
+- `keys_file` (str | Path, optional): Path to keys storage file. Default: "keys.json"
+- `env_prefix` (str, optional): Prefix for environment variables. Default: "API"
+- `encryption_key` (str, optional): Key for encrypting stored keys. Default: None (auto-generated)
+
+### Methods
+
+#### add_key
+
+Add a new API key with configuration.
+
+```python
+key = key_manager.add_key(
+    name="service_name",
+    key="your-api-key",
+    scopes=["read:data", "write:data"],
+    expires_at=datetime.now(timezone.utc) + timedelta(days=90),
+    rate_limit=10.0,
+    burst_limit=20
+)
+```
+
+**Parameters:**
+- `name` (str): Key identifier
+- `key` (str): API key value
+- `scopes` (List[str], optional): Access scopes. Default: []
+- `expires_at` (datetime, optional): Expiration date. Default: None
+- `rate_limit` (float, optional): Requests per second. Default: 10.0
+- `burst_limit` (int, optional): Maximum burst size. Default: 20
+
+**Returns:**
+- `APIKeyConfig`: Created key configuration
+
+**Raises:**
+- `ValidationError`: If any input is invalid
+- `InvalidKeyError`: If key already exists
+- `ConfigurationError`: If key cannot be saved
+
+#### get_key
+
+Get an API key by name.
+
+```python
+key = key_manager.get_key("service_name")
+if key and key.is_valid:
+    api_key = key.key.get_secret_value()
+```
+
+**Parameters:**
+- `name` (str): Key identifier
+
+**Returns:**
+- `Optional[APIKeyConfig]`: Key configuration if found and valid
+
+**Raises:**
+- `ValidationError`: If name is invalid
+- `InvalidKeyError`: If key is not found
+- `KeyExpiredError`: If key is expired
+
+#### rotate_key
+
+Rotate an existing API key.
+
+```python
+new_key = key_manager.rotate_key(
+    name="service_name",
+    new_key="new-api-key",
+    expires_at=datetime.now(timezone.utc) + timedelta(days=90),
+    rate_limit=20.0,
+    burst_limit=40
+)
+```
+
+**Parameters:**
+- `name` (str): Key identifier
+- `new_key` (str): New API key value
+- `expires_at` (datetime, optional): New expiration date
+- `rate_limit` (float, optional): New rate limit
+- `burst_limit` (int, optional): New burst limit
+
+**Returns:**
+- `APIKeyConfig`: Updated key configuration
+
+**Raises:**
+- `ValidationError`: If any input is invalid
+- `InvalidKeyError`: If key does not exist
+- `ConfigurationError`: If key cannot be saved
+
+#### remove_key
+
+Remove an API key.
+
+```python
+key_manager.remove_key("service_name")
+```
+
+**Parameters:**
+- `name` (str): Key identifier
+
+**Raises:**
+- `ValidationError`: If name is invalid
+- `InvalidKeyError`: If key does not exist
+- `ConfigurationError`: If key cannot be removed
+
+#### list_keys
+
+List all valid API keys.
+
+```python
+keys = key_manager.list_keys()
+for name, key in keys.items():
+    print(f"{name}: {key.scopes}")
+```
+
+**Returns:**
+- `Dict[str, APIKeyConfig]`: Dictionary of valid key configurations
+
+#### check_rate_limit
+
+Check rate limit for a key.
+
+```python
+try:
+    wait_time = await key_manager.check_rate_limit("service_name")
+    if wait_time > 0:
+        await asyncio.sleep(wait_time)
+except RateLimitError as e:
+    # Handle rate limit exceeded
+    logger.warning(f"Rate limited: {e.wait_time}s")
+```
+
+**Parameters:**
+- `name` (str): Key identifier
+
+**Returns:**
+- `float`: Wait time in seconds if rate limited, 0 otherwise
+
+**Raises:**
+- `InvalidKeyError`: If key does not exist
+- `KeyExpiredError`: If key is expired
+- `RateLimitError`: If rate limit is exceeded
+
+## API Key Configuration
+
+### APIKeyConfig Class
+
+Configuration class for API keys with validation.
+
+```python
+from tools.security import APIKeyConfig
+from pydantic import SecretStr
+
+config = APIKeyConfig(
+    key=SecretStr("api-key"),
+    name="service_name",
+    scopes=["read:data"],
+    expires_at=datetime.now(timezone.utc) + timedelta(days=90),
+    rate_limit=10.0,
+    burst_limit=20
+)
+```
+
+#### Attributes
+
+- `key` (SecretStr): API key value (masked in logs)
+- `name` (str): Key identifier
+- `created_at` (datetime): Creation timestamp
+- `expires_at` (Optional[datetime]): Expiration date
+- `scopes` (List[str]): Access scopes
+- `is_active` (bool): Whether key is active
+- `rate_limit` (float): Requests per second
+- `burst_limit` (int): Maximum burst size
+
+#### Properties
+
+- `is_expired` (bool): Check if key is expired
+- `is_valid` (bool): Check if key is valid for use
+
+## Rate Limiting
+
+### Configuration
+
+Rate limiting is configured per key using token bucket algorithm:
+
+```python
+# Configure rate limits
+key = key_manager.add_key(
+    name="service_name",
+    key="api-key",
+    rate_limit=10.0,    # 10 requests per second
+    burst_limit=20      # Allow bursts up to 20
+)
+
+# Check rate limit before requests
+try:
+    wait_time = await key_manager.check_rate_limit("service_name")
+    if wait_time > 0:
+        # Wait before next request
+        await asyncio.sleep(wait_time)
+except RateLimitError as e:
+    # Rate limit exceeded
+    logger.warning(f"Rate limited for {e.wait_time}s")
+```
+
+### Best Practices
+
+1. Set appropriate limits based on service capacity
+2. Configure burst limits for traffic spikes
+3. Implement client-side rate limiting
+4. Use exponential backoff for retries
+5. Monitor rate limit violations
+
+## Error Handling
+
+### Error Types
+
+- `SecurityError`: Base class for security errors
+- `AuthenticationError`: Authentication failures
+- `AuthorizationError`: Permission issues
+- `InvalidKeyError`: Invalid/missing keys
+- `KeyExpiredError`: Expired keys
+- `RateLimitError`: Rate limit violations
+- `EncryptionError`: Encryption issues
+- `ValidationError`: Input validation failures
+- `ConfigurationError`: Configuration issues
+
+### Error Handling Example
+
+```python
+from tools.errors import (
+    SecurityError,
+    InvalidKeyError,
+    KeyExpiredError,
+    RateLimitError
+)
+
+try:
+    # Attempt to use key
+    key = key_manager.get_key("service_name")
+    if not key or not key.is_valid:
+        raise InvalidKeyError("Invalid key")
+
+    # Check rate limit
+    wait_time = await key_manager.check_rate_limit("service_name")
+    if wait_time > 0:
+        await asyncio.sleep(wait_time)
+
+    # Use key
+    api_key = key.key.get_secret_value()
+
+except InvalidKeyError as e:
+    logger.error("Invalid API key", service="service_name")
+    raise HTTPError(401, "Authentication failed")
+
+except KeyExpiredError as e:
+    logger.error("Expired API key", service="service_name")
+    raise HTTPError(401, "Authentication failed")
+
+except RateLimitError as e:
+    logger.warning("Rate limit exceeded",
+        service="service_name",
+        wait_time=e.wait_time
+    )
+    raise HTTPError(429, f"Rate limit exceeded. Try again in {e.wait_time}s")
+
+except SecurityError as e:
+    logger.error("Security error",
+        service="service_name",
+        error=str(e)
+    )
+    raise HTTPError(500, "Internal security error")
+```
+
+## Examples
+
+### Basic Usage
+
+```python
+# Initialize
+from tools.security import key_manager
+
+# Add new key
+key = key_manager.add_key(
+    name="my_service",
+    key="my-api-key",
+    scopes=["read:data"]
+)
+
+# Use key
+try:
+    key = key_manager.get_key("my_service")
+    if key and key.is_valid:
+        api_key = key.key.get_secret_value()
+        # Use api_key...
+except SecurityError as e:
+    logger.error("Security error", error=str(e))
+```
+
+### Key Rotation
+
+```python
+# Generate new key
+import secrets
+import string
+new_key = ''.join(secrets.choice(string.ascii_letters + string.digits + '_.-')
+                  for _ in range(32))
+
+# Rotate key
+try:
+    key = key_manager.rotate_key(
+        name="my_service",
+        new_key=new_key,
+        expires_at=datetime.now(timezone.utc) + timedelta(days=90)
+    )
+    logger.info("Key rotated successfully", service="my_service")
+except SecurityError as e:
+    logger.error("Key rotation failed", error=str(e))
+```
+
+### Rate Limited Service
+
+```python
+async def make_api_request(service_name: str):
+    try:
+        # Get key
+        key = key_manager.get_key(service_name)
+        if not key or not key.is_valid:
+            raise InvalidKeyError("Invalid key")
+
+        # Check rate limit
+        wait_time = await key_manager.check_rate_limit(service_name)
+        if wait_time > 0:
+            await asyncio.sleep(wait_time)
+
+        # Make request
+        api_key = key.key.get_secret_value()
+        response = await make_request(api_key)
+        return response
+
+    except RateLimitError as e:
+        logger.warning("Rate limited",
+            service=service_name,
+            wait_time=e.wait_time
+        )
+        raise
+```
+
+For more examples and best practices, see:
+- [Security Documentation](../SECURITY.md)
+- [Quick Start Guide](./security_quickstart.md)
+- [Error Handling Guide](./errors.md)
+- [Monitoring Guide](./monitoring.md)

docs/api_reference.md

@@ -0,0 +1,143 @@
+# API Reference
+
+## Core Components
+
+### Tool Registry
+
+The `ToolRegistry` class manages and instantiates tools in the AI Assistant framework.
+
+```python
+from tools import ToolRegistry, get_tool, get_all_tools
+```
+
+#### Methods
+
+- `get_tool(name: str) -> BaseTool`: Get a tool instance by name
+- `get_all_tools() -> dict[str, BaseTool]`: Get all registered tools
+- `register(tool_class: Type[T]) -> Type[T]`: Register a tool class (decorator)
+- `clear() -> None`: Clear all registered tools (mainly for testing)
+
+### Base Tool
+
+The `BaseTool` abstract base class defines the interface for all tools.
+
+```python
+from tools import BaseTool
+```
+
+#### Required Properties
+
+- `name -> str`: The unique name of the tool
+- `description -> str`: A description of what the tool does
+
+## Error Handling
+
+### API Errors
+
+The framework provides specialized error types for API-related issues:
+
+```python
+from tools.exceptions import APIError, APITimeoutError, APIRateLimitError
+```
+
+#### Error Types
+
+- `APIError`: Base exception for API-related errors
+- `APITimeoutError`: Raised when an API request times out
+- `APIRateLimitError`: Raised when API rate limits are exceeded
+
+### Error Recovery
+
+#### Circuit Breaker
+
+The `CircuitBreaker` class prevents cascading failures:
+
+```python
+from tools.error_recovery import CircuitBreaker
+
+circuit_breaker = CircuitBreaker(
+    failure_threshold=5,
+    reset_timeout=60.0,
+    half_open_timeout=30.0
+)
+```
+
+#### Retry Configuration
+
+The `RetryConfig` class configures retry behavior:
+
+```python
+from tools.error_recovery import RetryConfig
+
+retry_config = RetryConfig(
+    max_retries=3,
+    initial_delay=1.0,
+    max_delay=60.0,
+    exponential_base=2.0,
+    jitter=0.1
+)
+```
+
+## API Logging
+
+The `log_api_call` decorator provides comprehensive API call logging:
+
+```python
+from tools.api_logging import log_api_call
+
+@log_api_call(
+    log_response=True,
+    log_request_body=True,
+    timeout=5.0,
+    retry_config=RetryConfig(max_retries=3),
+    circuit_breaker=CircuitBreaker(failure_threshold=5)
+)
+def my_api_function():
+    pass
+```
+
+### Features
+
+- Request/response logging with sanitization
+- Timeout handling
+- Retry mechanism with exponential backoff
+- Circuit breaker integration
+- Rate limit handling
+
+## Tools
+
+### Timezone Tools
+
+The `TimezoneTools` class provides timezone conversion functionality:
+
+```python
+from tools import TimezoneTools
+
+timezone_tool = TimezoneTools()
+```
+
+#### Methods
+
+- `get_current_time(tz: str = "UTC") -> datetime`: Get current time in specified timezone
+- `list_common_timezones() -> List[str]`: Get list of common timezone names
+- `is_valid_timezone(tz: str) -> bool`: Check if timezone name is valid
+
+### Weather Tool
+
+The `WeatherTool` class provides weather information by ZIP code:
+
+```python
+from tools.weather import WeatherTool
+
+weather_tool = WeatherTool(
+    api_base_url="http://api.weatherapi.com/v1",
+    cache_timeout=300
+)
+```
+
+#### Methods
+
+- `__call__(zipcode: str) -> str`: Get weather information for a ZIP code
+- Includes built-in caching
+- Validates ZIP code format
+- Handles API errors and rate limiting 

docs/error_handling.md

@@ -0,0 +1,201 @@
+# Error Handling Guide
+
+## Overview
+
+The AI Assistant framework provides a robust error handling system with several key features:
+- Custom exception types for different error scenarios
+- Automatic retry mechanism with exponential backoff
+- Circuit breaker pattern to prevent cascading failures
+- Comprehensive error logging
+
+## Exception Hierarchy
+
+```
+ToolError
+└── APIError
+    ├── APITimeoutError
+    └── APIRateLimitError
+```
+
+### Base Exceptions
+
+#### ToolError
+Base exception class for all tool-related errors.
+
+#### APIError
+```python
+from tools.exceptions import APIError
+
+raise APIError(
+    message="API request failed",
+    endpoint="/api/v1/data",
+    status_code=500,
+    response_body="Internal server error",
+    request_data={"key": "value"},
+    tool_name="my_tool"
+)
+```
+
+Properties:
+- `message`: Error description
+- `endpoint`: The API endpoint that failed
+- `status_code`: HTTP status code (optional)
+- `response_body`: Response from the API (optional)
+- `request_data`: Data sent in the request (optional)
+- `tool_name`: Name of the tool where the error occurred
+- `timestamp`: When the error occurred
+
+### Specialized Exceptions
+
+#### APITimeoutError
+```python
+from tools.exceptions import APITimeoutError
+
+raise APITimeoutError(
+    endpoint="/api/v1/data",
+    timeout=5.0,
+    request_data={"key": "value"},
+    tool_name="my_tool"
+)
+```
+
+Additional properties:
+- `timeout`: The timeout duration in seconds
+
+#### APIRateLimitError
+```python
+from tools.exceptions import APIRateLimitError
+
+raise APIRateLimitError(
+    endpoint="/api/v1/data",
+    retry_after=60,
+    request_data={"key": "value"},
+    tool_name="my_tool"
+)
+```
+
+Additional properties:
+- `retry_after`: Seconds to wait before retrying
+
+## Error Recovery
+
+### Circuit Breaker Pattern
+
+The circuit breaker prevents cascading failures by temporarily stopping operations after repeated failures.
+
+```python
+from tools.error_recovery import CircuitBreaker
+
+circuit_breaker = CircuitBreaker(
+    failure_threshold=5,    # Open after 5 failures
+    reset_timeout=60.0,     # Try to reset after 60 seconds
+    half_open_timeout=30.0  # Wait 30 seconds between half-open attempts
+)
+```
+
+States:
+1. **Closed**: Normal operation
+2. **Open**: Failing fast, no operations allowed
+3. **Half-Open**: Testing if system has recovered
+
+### Retry Mechanism
+
+The retry mechanism automatically retries failed operations with exponential backoff.
+
+```python
+from tools.error_recovery import RetryConfig
+
+retry_config = RetryConfig(
+    max_retries=3,           # Maximum number of retry attempts
+    initial_delay=1.0,       # Initial delay between retries (seconds)
+    max_delay=60.0,         # Maximum delay between retries (seconds)
+    exponential_base=2.0,    # Base for exponential backoff
+    jitter=0.1              # Random jitter factor (0.0-1.0)
+)
+```
+
+Features:
+- Exponential backoff with jitter
+- Configurable retry conditions
+- Automatic handling of rate limits
+- Integration with circuit breaker
+
+## Combining Error Recovery Mechanisms
+
+Use the `@log_api_call` decorator to combine logging, retries, and circuit breaker:
+
+```python
+from tools.api_logging import log_api_call
+from tools.error_recovery import RetryConfig, CircuitBreaker
+
+@log_api_call(
+    retry_config=RetryConfig(
+        max_retries=3,
+        initial_delay=1.0
+    ),
+    circuit_breaker=CircuitBreaker(
+        failure_threshold=5
+    )
+)
+def call_api():
+    # Your API call here
+    pass
+```
+
+## Best Practices
+
+1. **Use Specific Exceptions**
+   ```python
+   # Good
+   raise APITimeoutError(endpoint="/api/data", timeout=5.0)
+   
+   # Avoid
+   raise Exception("API timeout")
+   ```
+
+2. **Include Context**
+   ```python
+   # Good
+   raise APIError(
+       message="Invalid response format",
+       endpoint="/api/data",
+       response_body=response_text
+   )
+   
+   # Avoid
+   raise APIError("Invalid response format")
+   ```
+
+3. **Configure Recovery Appropriately**
+   ```python
+   # Good - Configured for specific use case
+   RetryConfig(
+       max_retries=3,
+       initial_delay=0.1,
+       max_delay=1.0
+   )
+   
+   # Avoid - Using defaults without consideration
+   RetryConfig()
+   ```
+
+4. **Handle Rate Limits**
+   ```python
+   # Good
+   except APIRateLimitError as e:
+       wait_time = e.retry_after or 60
+       time.sleep(wait_time)
+   
+   # Avoid
+   except APIRateLimitError:
+       time.sleep(60)  # Hard-coded wait time
+   ```
+
+5. **Log Errors Appropriately**
+   ```python
+   # Good
+   @log_api_call(log_response=True, log_request_body=True)
+   
+   # Avoid
+   # No logging or manual logging without sanitization
+   ``` 

docs/errors.md

@@ -0,0 +1,434 @@
+# Error Handling Guide
+
+## Overview
+
+This guide covers error handling in the API key management system, including error types, best practices, and examples.
+
+## Table of Contents
+
+1. [Error Types](#error-types)
+2. [Error Handling Best Practices](#error-handling-best-practices)
+3. [Common Error Scenarios](#common-error-scenarios)
+4. [Logging Best Practices](#logging-best-practices)
+5. [Error Recovery](#error-recovery)
+
+## Error Types
+
+### SecurityError
+
+Base class for all security-related errors.
+
+```python
+try:
+    # Security operation
+    raise SecurityError("Security violation")
+except SecurityError as e:
+    print(f"Error code: {e.code}")  # SECURITY_ERROR
+    print(f"Message: {e.message}")  # Security violation
+```
+
+### AuthenticationError
+
+Raised when authentication fails.
+
+```python
+try:
+    raise AuthenticationError("Invalid credentials")
+except AuthenticationError as e:
+    print(f"Error code: {e.code}")  # AUTH_ERROR
+    print(f"Message: {e.message}")  # Invalid credentials
+```
+
+### AuthorizationError
+
+Raised when authorization fails.
+
+```python
+try:
+    raise AuthorizationError("Insufficient permissions")
+except AuthorizationError as e:
+    print(f"Error code: {e.code}")  # ACCESS_DENIED
+    print(f"Message: {e.message}")  # Insufficient permissions
+```
+
+### InvalidKeyError
+
+Raised when an API key is invalid.
+
+```python
+try:
+    key = key_manager.get_key("nonexistent")
+    if not key:
+        raise InvalidKeyError("Key not found")
+except InvalidKeyError as e:
+    print(f"Error code: {e.code}")  # INVALID_KEY
+    print(f"Message: {e.message}")  # Key not found
+```
+
+### KeyExpiredError
+
+Raised when an API key has expired.
+
+```python
+try:
+    key = key_manager.get_key("expired_key")
+    if key.is_expired:
+        raise KeyExpiredError("Key has expired")
+except KeyExpiredError as e:
+    print(f"Error code: {e.code}")  # KEY_EXPIRED
+    print(f"Message: {e.message}")  # Key has expired
+```
+
+### RateLimitError
+
+Raised when rate limit is exceeded.
+
+```python
+try:
+    await key_manager.check_rate_limit("service")
+except RateLimitError as e:
+    print(f"Error code: {e.code}")     # RATE_LIMITED
+    print(f"Message: {e.message}")     # Rate limit exceeded
+    print(f"Wait time: {e.wait_time}") # Time to wait in seconds
+```
+
+### EncryptionError
+
+Raised when encryption/decryption fails.
+
+```python
+try:
+    key_manager = KeyManager(encryption_key="invalid-key")
+except EncryptionError as e:
+    print(f"Error code: {e.code}")  # ENCRYPTION_ERROR
+    print(f"Message: {e.message}")  # Failed to decrypt
+```
+
+### ValidationError
+
+Raised when validation fails.
+
+```python
+try:
+    key_manager.add_key("service", "invalid@key")
+except ValidationError as e:
+    print(f"Error code: {e.code}")   # VALIDATION_ERROR
+    print(f"Message: {e.message}")   # Invalid key format
+    print(f"Field: {e.field}")      # key
+```
+
+### ConfigurationError
+
+Raised when configuration is invalid.
+
+```python
+try:
+    key_manager = KeyManager(env_prefix="123")  # Must start with letter
+except ConfigurationError as e:
+    print(f"Error code: {e.code}")  # CONFIG_ERROR
+    print(f"Message: {e.message}")  # Invalid prefix
+```
+
+## Error Handling Best Practices
+
+### 1. Use Specific Error Types
+
+```python
+# ❌ WRONG - Too generic
+try:
+    key = key_manager.get_key("service")
+except Exception as e:
+    logger.error("Error occurred")
+
+# ✅ RIGHT - Specific error handling
+try:
+    key = key_manager.get_key("service")
+except InvalidKeyError:
+    logger.error("Invalid key", service="service")
+    raise HTTPError(401)
+except KeyExpiredError:
+    logger.error("Expired key", service="service")
+    raise HTTPError(401)
+except SecurityError as e:
+    logger.error("Security error", error=str(e))
+    raise HTTPError(500)
+```
+
+### 2. Never Expose Sensitive Data
+
+```python
+# ❌ WRONG - Exposing sensitive data
+except InvalidKeyError as e:
+    logger.error(f"Invalid key: {api_key}")
+    return {"error": f"Invalid key: {api_key}"}
+
+# ✅ RIGHT - Safe error handling
+except InvalidKeyError as e:
+    logger.error("Invalid key used", service="service_name")
+    return {"error": "Authentication failed"}
+```
+
+### 3. Proper Error Propagation
+
+```python
+# ❌ WRONG - Swallowing errors
+try:
+    key = key_manager.get_key("service")
+except SecurityError:
+    pass  # Don't do this!
+
+# ✅ RIGHT - Proper propagation
+try:
+    key = key_manager.get_key("service")
+except SecurityError as e:
+    logger.error("Security error", error=str(e))
+    raise  # Re-raise or raise appropriate HTTP error
+```
+
+### 4. Context Preservation
+
+```python
+# ❌ WRONG - Lost context
+try:
+    key = key_manager.get_key("service")
+except SecurityError as e:
+    raise RuntimeError("Error occurred")
+
+# ✅ RIGHT - Preserve context
+try:
+    key = key_manager.get_key("service")
+except SecurityError as e:
+    logger.error("Security error",
+        service="service",
+        error_code=e.code,
+        error_type=type(e).__name__
+    )
+    raise HTTPError(500, str(e)) from e
+```
+
+## Common Error Scenarios
+
+### Authentication Failures
+
+```python
+from tools.errors import AuthenticationError, InvalidKeyError, KeyExpiredError
+
+def authenticate_request(service_name: str, api_key: str) -> bool:
+    try:
+        # Validate key
+        key = key_manager.get_key(service_name)
+        if not key or not key.is_valid:
+            raise InvalidKeyError("Invalid key")
+
+        # Verify key value
+        if key.key.get_secret_value() != api_key:
+            raise AuthenticationError("Invalid credentials")
+
+        return True
+
+    except InvalidKeyError:
+        logger.error("Invalid API key", service=service_name)
+        raise HTTPError(401, "Authentication failed")
+
+    except KeyExpiredError:
+        logger.error("Expired API key", service=service_name)
+        raise HTTPError(401, "Authentication failed")
+
+    except AuthenticationError:
+        logger.error("Authentication failed", service=service_name)
+        raise HTTPError(401, "Authentication failed")
+```
+
+### Rate Limiting
+
+```python
+async def rate_limited_request(service_name: str):
+    try:
+        # Check rate limit
+        wait_time = await key_manager.check_rate_limit(service_name)
+        if wait_time > 0:
+            # Implement backoff strategy
+            await asyncio.sleep(wait_time)
+
+        # Make request
+        return await make_request()
+
+    except RateLimitError as e:
+        logger.warning("Rate limit exceeded",
+            service=service_name,
+            wait_time=e.wait_time
+        )
+        raise HTTPError(
+            429,
+            f"Too many requests. Try again in {e.wait_time} seconds"
+        )
+```
+
+### Configuration Issues
+
+```python
+def setup_key_manager() -> KeyManager:
+    try:
+        # Load configuration
+        encryption_key = os.getenv("API_ENCRYPTION_KEY")
+        if not encryption_key:
+            raise ConfigurationError("Missing encryption key")
+
+        # Initialize manager
+        return KeyManager(
+            keys_file="keys.json",
+            encryption_key=encryption_key
+        )
+
+    except ConfigurationError as e:
+        logger.error("Configuration error",
+            error=str(e),
+            code=e.code
+        )
+        raise SystemExit("Failed to initialize key manager")
+
+    except EncryptionError as e:
+        logger.error("Encryption error",
+            error=str(e),
+            code=e.code
+        )
+        raise SystemExit("Failed to initialize encryption")
+```
+
+## Logging Best Practices
+
+### 1. Use Structured Logging
+
+```python
+import structlog
+
+logger = structlog.get_logger()
+
+try:
+    key = key_manager.get_key("service")
+except SecurityError as e:
+    logger.error("security_error",
+        service="service",
+        error_code=e.code,
+        error_type=type(e).__name__,
+        error_message=str(e)
+    )
+```
+
+### 2. Appropriate Log Levels
+
+```python
+# Error - Security incidents
+logger.error("security_violation",
+    service="service",
+    error_code="AUTH_ERROR"
+)
+
+# Warning - Rate limits, temporary issues
+logger.warning("rate_limit_exceeded",
+    service="service",
+    wait_time=1.5
+)
+
+# Info - Normal security events
+logger.info("key_rotated",
+    service="service",
+    expires_in_days=90
+)
+
+# Debug - Detailed security info
+logger.debug("rate_limit_check",
+    service="service",
+    current_rate=5.0,
+    limit=10.0
+)
+```
+
+### 3. Context Preservation
+
+```python
+# Add context to all logs
+logger = logger.bind(
+    service="my_service",
+    environment="production"
+)
+
+try:
+    key = key_manager.get_key("service")
+except SecurityError as e:
+    logger.error("security_error",
+        error_code=e.code,
+        error_message=str(e)
+    )
+```
+
+## Error Recovery
+
+### 1. Automatic Retry
+
+```python
+from tenacity import retry, stop_after_attempt, wait_exponential
+
+@retry(
+    stop=stop_after_attempt(3),
+    wait=wait_exponential(multiplier=1, min=4, max=10),
+    retry=retry_if_exception_type(RateLimitError)
+)
+async def make_rate_limited_request(service_name: str):
+    wait_time = await key_manager.check_rate_limit(service_name)
+    if wait_time > 0:
+        await asyncio.sleep(wait_time)
+    return await make_request()
+```
+
+### 2. Fallback Strategies
+
+```python
+def get_api_key(service_name: str) -> Optional[str]:
+    try:
+        # Try primary key
+        key = key_manager.get_key(service_name)
+        if key and key.is_valid:
+            return key.key.get_secret_value()
+
+        # Try fallback key
+        fallback_key = key_manager.get_key(f"{service_name}_fallback")
+        if fallback_key and fallback_key.is_valid:
+            return fallback_key.key.get_secret_value()
+
+        return None
+
+    except SecurityError as e:
+        logger.error("Failed to get API key",
+            service=service_name,
+            error=str(e)
+        )
+        return None
+```
+
+### 3. Circuit Breaker
+
+```python
+from circuitbreaker import circuit
+
+@circuit(
+    failure_threshold=5,
+    recovery_timeout=60,
+    expected_exception=SecurityError
+)
+async def make_secure_request(service_name: str):
+    key = key_manager.get_key(service_name)
+    if not key or not key.is_valid:
+        raise InvalidKeyError("Invalid key")
+
+    wait_time = await key_manager.check_rate_limit(service_name)
+    if wait_time > 0:
+        await asyncio.sleep(wait_time)
+
+    return await make_request(key.key.get_secret_value())
+```
+
+For more information, see:
+- [API Documentation](./api.md)
+- [Security Guide](../SECURITY.md)
+- [Monitoring Guide](./monitoring.md)

docs/getting_started.md

@@ -0,0 +1,202 @@
+# Getting Started
+
+## Installation
+
+Install the AI Assistant framework using pip:
+
+```bash
+pip install ai-assistant
+```
+
+## Quick Start
+
+### 1. Basic Tool Usage
+
+```python
+from tools import get_tool
+
+# Get a tool instance
+timezone_tool = get_tool("timezone")
+
+# Use the tool
+current_time = timezone_tool.get_current_time("America/New_York")
+print(f"Current time: {current_time}")
+```
+
+### 2. Creating a Custom Tool
+
+```python
+from tools import BaseTool, register_tool
+
+@register_tool
+class MyCustomTool(BaseTool):
+    @property
+    def name(self) -> str:
+        return "my_custom_tool"
+    
+    @property
+    def description(self) -> str:
+        return "Description of what my tool does"
+    
+    def my_method(self) -> str:
+        return "Hello from my custom tool!"
+```
+
+## Core Concepts
+
+### 1. Tool Registry
+
+The tool registry manages all available tools:
+
+```python
+from tools import ToolRegistry, get_all_tools
+
+# Get all registered tools
+tools = get_all_tools()
+
+# Get a specific tool
+weather_tool = tools["weather"]
+```
+
+### 2. API Integration
+
+Example of making an API call with error handling:
+
+```python
+from tools.api_logging import log_api_call
+from tools.error_recovery import RetryConfig, CircuitBreaker
+
+@log_api_call(
+    log_response=True,
+    retry_config=RetryConfig(max_retries=3),
+    circuit_breaker=CircuitBreaker(failure_threshold=5)
+)
+def get_weather(zipcode: str) -> dict:
+    response = requests.get(
+        f"https://api.weather.com/v1/{zipcode}",
+        headers={"Authorization": "Bearer YOUR_API_KEY"}
+    )
+    response.raise_for_status()
+    return response.json()
+```
+
+### 3. Error Handling
+
+Example of handling API errors:
+
+```python
+from tools.exceptions import APIError, APITimeoutError, APIRateLimitError
+
+try:
+    result = get_weather("12345")
+except APITimeoutError as e:
+    print(f"Request timed out after {e.timeout} seconds")
+except APIRateLimitError as e:
+    print(f"Rate limited, retry after {e.retry_after} seconds")
+except APIError as e:
+    print(f"API error: {e.message}")
+```
+
+## Common Use Cases
+
+### 1. Weather Information
+
+```python
+from tools.weather import WeatherTool
+
+weather = WeatherTool()
+forecast = weather("90210")  # Get weather for Beverly Hills
+print(forecast)
+```
+
+### 2. Timezone Conversion
+
+```python
+from tools import TimezoneTools
+
+tz = TimezoneTools()
+
+# Get current time in different timezones
+nyc_time = tz.get_current_time("America/New_York")
+tokyo_time = tz.get_current_time("Asia/Tokyo")
+
+# List available timezones
+timezones = tz.list_common_timezones()
+```
+
+## Configuration
+
+### 1. Logging Setup
+
+```python
+import logging
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+```
+
+### 2. API Configuration
+
+```python
+import os
+
+# Set API keys in environment variables
+os.environ['WEATHER_API_KEY'] = 'your_api_key_here'
+```
+
+## Best Practices
+
+1. **Use Environment Variables for Secrets**
+   ```python
+   # Good
+   api_key = os.getenv('API_KEY')
+   
+   # Avoid
+   api_key = 'hardcoded_secret'
+   ```
+
+2. **Enable Appropriate Logging**
+   ```python
+   # Development
+   @log_api_call(log_response=True, log_request_body=True)
+   
+   # Production
+   @log_api_call(log_response=False, log_request_body=False)
+   ```
+
+3. **Handle Errors Gracefully**
+   ```python
+   try:
+       result = api_call()
+   except APIError as e:
+       logger.error(f"API error: {e.message}")
+       # Implement fallback behavior
+   ```
+
+4. **Use Type Hints**
+   ```python
+   def process_data(data: Dict[str, Any]) -> List[str]:
+       return [item['name'] for item in data['items']]
+   ```
+
+5. **Document Your Tools**
+   ```python
+   class MyTool(BaseTool):
+       """
+       My custom tool for processing data.
+       
+       Attributes:
+           name: The unique identifier for this tool
+           description: What this tool does
+       """
+   ```
+
+## Next Steps
+
+1. Read the [API Reference](api_reference.md) for detailed documentation
+2. Learn about [Error Handling](error_handling.md)
+3. Explore the [Logging System](logging.md)
+4. Check out example implementations in the `examples/` directory 

docs/logging.md

@@ -0,0 +1,231 @@
+# Logging System Documentation
+
+## Overview
+
+The AI Assistant framework provides a comprehensive logging system focused on API interactions and error handling. The system includes:
+- Request/response logging
+- Error tracking
+- Sensitive data sanitization
+- Integration with error recovery mechanisms
+
+## API Call Logging
+
+### Basic Usage
+
+```python
+from tools.api_logging import log_api_call
+
+@log_api_call()
+def my_api_function(url: str, data: dict):
+    # Function implementation
+    pass
+```
+
+### Configuration Options
+
+```python
+@log_api_call(
+    log_response=True,       # Log response bodies
+    log_request_body=True,   # Log request bodies
+    timeout=5.0,            # Request timeout in seconds
+    retry_config=RetryConfig(...),
+    circuit_breaker=CircuitBreaker(...)
+)
+```
+
+## Security Features
+
+### Header Sanitization
+
+The system automatically sanitizes sensitive information in headers:
+
+```python
+# Original headers
+headers = {
+    'Authorization': 'Bearer abc123',
+    'X-API-Key': 'secret_key',
+    'Content-Type': 'application/json'
+}
+
+# Logged headers
+{
+    'Authorization': '****',
+    'X-API-Key': '****',
+    'Content-Type': 'application/json'
+}
+```
+
+### URL Sanitization
+
+URLs are sanitized to remove sensitive parameters:
+
+```python
+# Original URL
+"https://api.example.com/v1/data?api_key=secret&user=john"
+
+# Logged URL
+"https://api.example.com/v1/data?api_key=****&user=john"
+```
+
+## Log Format
+
+### Request Logging
+
+```json
+{
+    "timestamp": "2024-01-01T12:00:00Z",
+    "function": "get_weather",
+    "url": "https://api.example.com/v1/weather",
+    "headers": {
+        "Authorization": "****",
+        "Content-Type": "application/json"
+    },
+    "body": {
+        "location": "New York"
+    }
+}
+```
+
+### Response Logging
+
+```json
+{
+    "timestamp": "2024-01-01T12:00:01Z",
+    "status": 200,
+    "url": "https://api.example.com/v1/weather",
+    "body": {
+        "temperature": 72,
+        "condition": "sunny"
+    }
+}
+```
+
+### Error Logging
+
+```json
+{
+    "timestamp": "2024-01-01T12:00:01Z",
+    "error_type": "APITimeoutError",
+    "error_message": "Request timed out after 5 seconds",
+    "url": "https://api.example.com/v1/weather"
+}
+```
+
+## Integration with Error Recovery
+
+The logging system integrates with the error recovery mechanisms:
+
+```python
+@log_api_call(
+    retry_config=RetryConfig(max_retries=3),
+    circuit_breaker=CircuitBreaker(failure_threshold=5)
+)
+def api_call():
+    # Each retry attempt is logged
+    # Circuit breaker state changes are logged
+    pass
+```
+
+Example retry log:
+```json
+{
+    "timestamp": "2024-01-01T12:00:01Z",
+    "message": "Retry attempt 1 of 3",
+    "delay": 1.0,
+    "error": "Connection refused"
+}
+```
+
+## Best Practices
+
+1. **Enable Appropriate Logging Levels**
+   ```python
+   # Good - Log both request and response for debugging
+   @log_api_call(log_response=True, log_request_body=True)
+   
+   # Production - Log only essential info
+   @log_api_call(log_response=False, log_request_body=False)
+   ```
+
+2. **Handle Sensitive Data**
+   ```python
+   # Good - Let the logger handle sanitization
+   headers = {'Authorization': f'Bearer {api_key}'}
+   
+   # Avoid - Manual sanitization
+   headers = {'Authorization': 'Bearer ****'}
+   ```
+
+3. **Include Context in Logs**
+   ```python
+   # Good
+   logger.info({
+       'action': 'api_call',
+       'endpoint': '/api/v1/data',
+       'status': 'success'
+   })
+   
+   # Avoid
+   logger.info('API call successful')
+   ```
+
+4. **Use Structured Logging**
+   ```python
+   # Good
+   logger.info(json.dumps({
+       'event': 'rate_limit',
+       'retry_after': 60,
+       'endpoint': '/api/v1/data'
+   }))
+   
+   # Avoid
+   logger.info(f"Rate limited on /api/v1/data, retry after 60s")
+   ```
+
+5. **Log at Appropriate Levels**
+   ```python
+   # Debug - Detailed information
+   logger.debug('Request parameters: %s', params)
+   
+   # Info - General operational events
+   logger.info('API call completed successfully')
+   
+   # Warning - Potential issues
+   logger.warning('Rate limit threshold approaching')
+   
+   # Error - Error events
+   logger.error('API call failed', exc_info=True)
+   ```
+
+## Configuration
+
+### Setting Up Logging
+
+```python
+import logging
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+
+# Get logger
+logger = logging.getLogger(__name__)
+```
+
+### Environment-Specific Configuration
+
+```python
+# Development
+logging.basicConfig(
+    level=logging.DEBUG,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+
+# Production
+logging.basicConfig(
+    level=logging.WARNING,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+    filename='api.log'
+) 

docs/security_quickstart.md

@@ -0,0 +1,130 @@
+# Security Quick Reference
+
+## Quick Start
+
+```python
+from tools.security import key_manager
+from datetime import datetime, timedelta, timezone
+
+# 1. Generate secure API key
+import secrets
+import string
+api_key = ''.join(secrets.choice(string.ascii_letters + string.digits + '_.-') for _ in range(32))
+
+# 2. Add key with security settings
+key = key_manager.add_key(
+    name="my_service",
+    key=api_key,
+    scopes=["read:data", "write:data"],
+    expires_at=datetime.now(timezone.utc) + timedelta(days=90),
+    rate_limit=10.0,
+    burst_limit=20
+)
+
+# 3. Use key securely
+try:
+    # Check rate limit
+    await key_manager.check_rate_limit("my_service")
+
+    # Use key
+    key = key_manager.get_key("my_service")
+    if key and key.is_valid:
+        api_key = key.key.get_secret_value()
+        # Use api_key for requests...
+
+except RateLimitError as e:
+    # Handle rate limiting
+    logger.warning(f"Rate limited: {e.wait_time}s")
+    await asyncio.sleep(e.wait_time)
+
+except (InvalidKeyError, KeyExpiredError) as e:
+    # Handle authentication errors
+    logger.error(f"Authentication failed: {e}")
+    raise HTTPError(401, "Authentication failed")
+```
+
+## Security Checklist
+
+✅ **API Keys**
+- [ ] 32+ character length
+- [ ] URL-safe characters only
+- [ ] 90-day expiration
+- [ ] Scoped permissions
+- [ ] Rate limits configured
+
+✅ **Environment**
+- [ ] `API_ENCRYPTION_KEY` set
+- [ ] `.env` in `.gitignore`
+- [ ] Secure file permissions
+- [ ] Different keys per environment
+
+✅ **Error Handling**
+- [ ] Catch security exceptions
+- [ ] No sensitive data in errors
+- [ ] Proper error logging
+- [ ] Rate limit handling
+
+✅ **Monitoring**
+- [ ] Security event logging
+- [ ] Rate limit monitoring
+- [ ] Failed auth tracking
+- [ ] Regular log review
+
+## Common Security Errors
+
+```python
+# ❌ WRONG - Insecure key generation
+api_key = "service123"  # Too short, predictable
+
+# ✅ RIGHT - Secure key generation
+api_key = ''.join(secrets.choice(string.ascii_letters + string.digits + '_.-') for _ in range(32))
+
+# ❌ WRONG - No error handling
+key = key_manager.get_key("service")
+api_key = key.key.get_secret_value()
+
+# ✅ RIGHT - Proper error handling
+try:
+    key = key_manager.get_key("service")
+    if not key or not key.is_valid:
+        raise InvalidKeyError("Invalid key")
+    api_key = key.key.get_secret_value()
+except SecurityError as e:
+    logger.error("Security error", error=str(e))
+    raise
+
+# ❌ WRONG - Exposed sensitive data
+except InvalidKeyError as e:
+    logger.error(f"Invalid key: {api_key}")  # Don't log keys!
+
+# ✅ RIGHT - Secure error logging
+except InvalidKeyError as e:
+    logger.error("Invalid key used", service="my_service")
+
+# ❌ WRONG - No rate limiting
+while True:
+    make_api_request(key)
+
+# ✅ RIGHT - Rate limit handling
+try:
+    wait_time = await key_manager.check_rate_limit("service")
+    if wait_time > 0:
+        await asyncio.sleep(wait_time)
+    make_api_request(key)
+except RateLimitError as e:
+    # Handle rate limiting
+    await asyncio.sleep(e.wait_time)
+```
+
+## Security Contacts
+
+- Security Team: security@example.com
+- Emergency Contact: +1-XXX-XXX-XXXX
+- Bug Reports: https://example.com/security
+
+## Additional Resources
+
+- [Full Security Documentation](../SECURITY.md)
+- [API Documentation](./api.md)
+- [Error Handling Guide](./errors.md)
+- [Monitoring Guide](./monitoring.md)

docs/user_guide.md

@@ -0,0 +1,813 @@
+# API Key Management System User Guide
+
+This guide provides comprehensive documentation for using the API key management system, including examples and best practices.
+
+## Table of Contents
+- [Developer Setup](#developer-setup)
+- [Command Reference](#command-reference)
+- [Quick Start](#quick-start)
+- [Key Management](#key-management)
+- [Security Features](#security-features)
+- [Rate Limiting](#rate-limiting)
+- [Error Handling](#error-handling)
+- [Best Practices](#best-practices)
+- [Examples](#examples)
+
+## Developer Setup
+
+### Prerequisites
+
+- Python 3.8 or higher
+- pip (Python package installer)
+- virtualenv (recommended)
+
+### Installation
+
+1. **Create and activate a virtual environment:**
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   ```
+
+2. **Install required packages:**
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+   The `requirements.txt` should include:
+   ```
+   pydantic>=2.0.0
+   cryptography>=41.0.0
+   aiohttp>=3.8.0
+   tenacity>=8.0.0
+   structlog>=23.0.0
+   cachetools>=5.0.0
+   ```
+
+3. **Set up environment variables:**
+   ```bash
+   # Create a .env file
+   touch .env
+
+   # Add required environment variables
+   echo "API_ENCRYPTION_KEY=$(python -c 'import base64; import os; print(base64.urlsafe_b64encode(os.urandom(32)).decode())')" >> .env
+   ```
+
+### Configuration
+
+1. **Basic setup:**
+   ```python
+   from tools.security import KeyManager
+
+   # Initialize with default settings
+   key_manager = KeyManager()
+   ```
+
+2. **Custom configuration:**
+   ```python
+   key_manager = KeyManager(
+       keys_file="custom_keys.json",     # Custom storage location
+       env_prefix="MYAPP",               # Custom environment prefix
+       encryption_key="your-secret-key"  # Custom encryption key
+   )
+   ```
+
+### Development Tools
+
+1. **Install development dependencies:**
+   ```bash
+   pip install -r requirements-dev.txt
+   ```
+
+   The `requirements-dev.txt` should include:
+   ```
+   pytest>=7.0.0
+   pytest-asyncio>=0.21.0
+   pytest-cov>=4.0.0
+   black>=23.0.0
+   isort>=5.0.0
+   mypy>=1.0.0
+   ```
+
+2. **Run tests:**
+   ```bash
+   # Run all tests
+   pytest
+
+   # Run with coverage
+   pytest --cov=tools
+
+   # Run specific test file
+   pytest tests/test_security.py
+   ```
+
+3. **Code formatting:**
+   ```bash
+   # Format code
+   black .
+
+   # Sort imports
+   isort .
+   ```
+
+4. **Type checking:**
+   ```bash
+   mypy tools/
+   ```
+
+### Project Structure
+
+```
+.
+├── tools/
+│   ├── __init__.py
+│   ├── security.py        # Key management implementation
+│   ├── errors.py         # Custom exceptions
+│   ├── validation.py     # Input validation
+│   ├── api_optimization.py # Rate limiting and optimization
+│   └── monitoring.py     # Performance monitoring
+├── tests/
+│   ├── __init__.py
+│   ├── test_security.py
+│   ├── test_validation.py
+│   └── test_errors.py
+├── docs/
+│   ├── api.md
+│   ├── security_quickstart.md
+│   ├── errors.md
+│   └── user_guide.md
+├── requirements.txt
+├── requirements-dev.txt
+└── README.md
+```
+
+### Debugging
+
+1. **Enable debug logging:**
+   ```python
+   import logging
+   logging.basicConfig(level=logging.DEBUG)
+   ```
+
+2. **Monitor rate limiting:**
+   ```python
+   async def monitor_rate_limits():
+       metrics = await key_manager.get_metrics()
+       print(f"Rate limit delays: {metrics['rate_limiting']['total_delays']}s")
+       print(f"Rate limit count: {metrics['rate_limiting']['count']}")
+   ```
+
+3. **Test key validation:**
+   ```python
+   from tools.validation import validate_api_key
+
+   try:
+       validate_api_key("test-key")
+   except ValidationError as e:
+       print(f"Validation error: {e.message}")
+   ```
+
+### Common Issues
+
+1. **Import Errors**
+   - Ensure your PYTHONPATH includes the project root
+   - Check that all dependencies are installed
+   - Verify virtual environment is activated
+
+2. **Encryption Errors**
+   - Verify encryption key is properly formatted (base64)
+   - Check environment variable is set correctly
+   - Ensure key file permissions are correct
+
+3. **Rate Limiting Issues**
+   - Monitor rate limit metrics
+   - Check burst limit configuration
+   - Verify clock synchronization
+
+4. **Performance Issues**
+   - Enable performance monitoring
+   - Check connection pool settings
+   - Monitor batch processing metrics
+
+### Contributing
+
+1. **Fork and clone the repository**
+   ```bash
+   git clone https://github.com/yourusername/api-key-manager.git
+   cd api-key-manager
+   ```
+
+2. **Create a feature branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+3. **Make changes and test**
+   ```bash
+   # Run tests
+   pytest
+
+   # Check code style
+   black .
+   isort .
+   mypy tools/
+
+   # Run full test suite with coverage
+   pytest --cov=tools --cov-report=html
+   ```
+
+4. **Submit a pull request**
+   - Include test coverage
+   - Update documentation
+   - Follow code style guidelines
+
+## Command Reference
+
+### Key Management Commands
+
+#### Initialize Key Manager
+```python
+KeyManager(
+    keys_file: str = "keys.json",
+    env_prefix: str = "API",
+    encryption_key: Optional[str] = None
+) -> KeyManager
+```
+Initialize a new key manager instance.
+- `keys_file`: Path to the key storage file (default: "keys.json")
+- `env_prefix`: Prefix for environment variables (default: "API")
+- `encryption_key`: Optional encryption key for storing keys
+
+#### Add Key
+```python
+key_manager.add_key(
+    name: str,
+    key: str,
+    scopes: Optional[List[str]] = None,
+    expires_at: Optional[datetime] = None,
+    rate_limit: float = 10.0,
+    burst_limit: int = 20
+) -> APIKeyConfig
+```
+Add a new API key to the manager.
+- `name`: Unique identifier for the key
+- `key`: The API key value
+- `scopes`: List of access scopes
+- `expires_at`: Optional expiration date
+- `rate_limit`: Requests per second (default: 10.0)
+- `burst_limit`: Maximum burst size (default: 20)
+
+#### Get Key
+```python
+key_manager.get_key(name: str) -> Optional[APIKeyConfig]
+```
+Retrieve an API key by name.
+- `name`: Key identifier
+- Returns: Key configuration or None if not found
+
+#### Rotate Key
+```python
+key_manager.rotate_key(
+    name: str,
+    new_key: str,
+    expires_at: Optional[datetime] = None,
+    rate_limit: Optional[float] = None,
+    burst_limit: Optional[int] = None
+) -> APIKeyConfig
+```
+Rotate an existing API key.
+- `name`: Key identifier
+- `new_key`: New API key value
+- `expires_at`: Optional new expiration date
+- `rate_limit`: Optional new rate limit
+- `burst_limit`: Optional new burst limit
+
+#### Remove Key
+```python
+key_manager.remove_key(name: str) -> None
+```
+Remove an API key.
+- `name`: Key identifier to remove
+
+#### List Keys
+```python
+key_manager.list_keys() -> Dict[str, APIKeyConfig]
+```
+List all valid API keys.
+- Returns: Dictionary of key names to configurations
+
+### Rate Limiting Commands
+
+#### Check Rate Limit
+```python
+await key_manager.check_rate_limit(name: str) -> float
+```
+Check if a key has exceeded its rate limit.
+- `name`: Key identifier
+- Returns: Wait time in seconds (0.0 if not rate limited)
+
+#### Rate Limiter Configuration
+```python
+RateLimiter(
+    rate: float,
+    burst: int
+) -> RateLimiter
+```
+Create a new rate limiter instance.
+- `rate`: Tokens (requests) per second
+- `burst`: Maximum burst size
+
+#### Acquire Rate Limit Token
+```python
+await rate_limiter.acquire(tokens: float = 1.0) -> float
+```
+Acquire tokens from the rate limiter.
+- `tokens`: Number of tokens to acquire (default: 1.0)
+- Returns: Wait time in seconds
+
+### Batch Processing Commands
+
+#### Initialize Batch Processor
+```python
+BatchProcessor(
+    batch_size: int = 100,
+    flush_interval: float = 1.0
+) -> BatchProcessor
+```
+Create a new batch processor.
+- `batch_size`: Maximum items per batch
+- `flush_interval`: Time between automatic flushes
+
+#### Add to Batch
+```python
+await batch_processor.add(item: Any) -> None
+```
+Add an item to the batch.
+- `item`: Item to add to batch
+
+#### Flush Batch
+```python
+await batch_processor.flush() -> None
+```
+Process current batch immediately.
+
+### Performance Monitoring Commands
+
+#### Initialize Monitor
+```python
+PerformanceMonitor(
+    metrics_ttl: int = 3600,
+    max_metrics: int = 1000
+) -> PerformanceMonitor
+```
+Create a new performance monitor.
+- `metrics_ttl`: Time to live for metrics in seconds
+- `max_metrics`: Maximum number of metrics to store
+
+#### Start Request Monitoring
+```python
+await monitor.start_request(endpoint: str) -> float
+```
+Start timing a request.
+- `endpoint`: API endpoint being called
+- Returns: Start timestamp
+
+#### End Request Monitoring
+```python
+await monitor.end_request(
+    endpoint: str,
+    start_time: float
+) -> None
+```
+Record the end of a request.
+- `endpoint`: API endpoint called
+- `start_time`: Start timestamp from start_request()
+
+#### Get Metrics
+```python
+monitor.get_metrics() -> Dict[str, Any]
+```
+Get comprehensive metrics report.
+- Returns: Dictionary of all collected metrics
+
+#### Log Metrics
+```python
+await monitor.log_metrics(logger: Any) -> None
+```
+Log current metrics using structlog.
+- `logger`: Structlog logger instance
+
+### API Client Commands
+
+#### Initialize API Client
+```python
+APIClient(
+    base_url: str,
+    pool_size: int = 10,
+    rate_limit: float = 10.0,
+    burst_limit: int = 20,
+    batch_size: int = 100,
+    **kwargs: Any
+) -> APIClient
+```
+Create optimized API client.
+- `base_url`: Base URL for API requests
+- `pool_size`: Connection pool size
+- `rate_limit`: Requests per second
+- `burst_limit`: Maximum burst size
+- `batch_size`: Default batch size
+- `**kwargs`: Additional client options
+
+#### Make Request
+```python
+await client.request(
+    method: str,
+    endpoint: str,
+    **kwargs: Any
+) -> Any
+```
+Make an API request with optimizations.
+- `method`: HTTP method
+- `endpoint`: API endpoint
+- `**kwargs`: Request parameters
+- Returns: JSON response
+
+#### Batch Request
+```python
+await client.batch_request(
+    method: str,
+    endpoint: str,
+    items: List[Dict[str, Any]]
+) -> List[Any]
+```
+Make batch API request.
+- `method`: HTTP method
+- `endpoint`: API endpoint
+- `items`: List of items to process
+- Returns: List of results
+
+### Validation Commands
+
+#### Validate API Key
+```python
+validate_api_key(key: str) -> str
+```
+Validate API key format.
+- `key`: API key to validate
+- Returns: Validated key or raises ValidationError
+
+#### Validate Name
+```python
+validate_name(name: str) -> str
+```
+Validate key name format.
+- `name`: Name to validate
+- Returns: Validated name or raises ValidationError
+
+#### Validate Scopes
+```python
+validate_scopes(scopes: List[str]) -> List[str]
+```
+Validate scope formats.
+- `scopes`: List of scopes to validate
+- Returns: Validated scopes or raises ValidationError
+
+#### Validate Rate Limits
+```python
+validate_rate_limits(
+    rate_limit: float,
+    burst_limit: int
+) -> Tuple[float, int]
+```
+Validate rate limiting parameters.
+- `rate_limit`: Requests per second
+- `burst_limit`: Maximum burst size
+- Returns: Tuple of validated limits or raises ValidationError
+
+## Quick Start
+
+```python
+from tools.security import KeyManager
+
+# Initialize the key manager
+key_manager = KeyManager(
+    keys_file="keys.json",
+    env_prefix="API"
+)
+
+# Add a new API key
+key_config = key_manager.add_key(
+    name="service_name",
+    key="api-key-123",
+    scopes=["read:data", "write:data"],
+    rate_limit=10.0,  # requests per second
+    burst_limit=20    # maximum burst size
+)
+
+# Use the key
+if key := key_manager.get_key("service_name"):
+    print(f"Key is valid: {key.is_valid}")
+    print(f"Scopes: {key.scopes}")
+```
+
+## Key Management
+
+### Creating Keys
+
+Keys can be created with various parameters:
+```python
+key_config = key_manager.add_key(
+    name="analytics_service",
+    key="api-key-xyz",
+    scopes=["read:analytics", "export:data"],
+    expires_at=datetime.now(timezone.utc) + timedelta(days=90),
+    rate_limit=5.0,
+    burst_limit=10
+)
+```
+
+### Rotating Keys
+
+For security, rotate keys periodically:
+```python
+new_config = key_manager.rotate_key(
+    name="analytics_service",
+    new_key="new-api-key-xyz",
+    expires_at=datetime.now(timezone.utc) + timedelta(days=90)
+)
+```
+
+### Environment Variables
+
+Keys can be loaded from environment variables:
+```bash
+export API_SERVICE_NAME_KEY=api-key-123
+export API_SERVICE_NAME_RATE_LIMIT=10.0
+export API_SERVICE_NAME_BURST_LIMIT=20
+```
+
+```python
+key = key_manager.get_key("service_name")  # Loads from environment
+```
+
+## Security Features
+
+### Encryption
+
+Keys are automatically encrypted at rest:
+```python
+# Keys are encrypted in storage
+key_manager = KeyManager(
+    encryption_key="your-encryption-key",  # Optional, can use env var
+    keys_file="keys.json"
+)
+```
+
+### Validation
+
+All inputs are validated:
+```python
+try:
+    key_config = key_manager.add_key(
+        name="service",
+        key="invalid-key!",  # Will raise ValidationError
+        scopes=["invalid:scope"]  # Will raise ValidationError
+    )
+except ValidationError as e:
+    print(f"Validation failed: {e.message}")
+```
+
+### Scopes
+
+Control access with scopes:
+```python
+key_config = key_manager.add_key(
+    name="limited_service",
+    key="api-key-123",
+    scopes=["read:only", "list:items"]
+)
+```
+
+## Rate Limiting
+
+### Basic Rate Limiting
+
+```python
+# Create key with rate limits
+key_config = key_manager.add_key(
+    name="service",
+    key="api-key-123",
+    rate_limit=10.0,  # 10 requests per second
+    burst_limit=20    # Allow bursts up to 20 requests
+)
+
+# Check rate limit before request
+async def make_request():
+    wait_time = await key_manager.check_rate_limit("service")
+    if wait_time > 0:
+        await asyncio.sleep(wait_time)
+    # Make request...
+```
+
+### Burst Handling
+
+```python
+# Allow higher burst rates for batch operations
+key_config = key_manager.add_key(
+    name="batch_service",
+    key="api-key-123",
+    rate_limit=50.0,   # 50 requests per second
+    burst_limit=100    # Allow bursts up to 100 requests
+)
+```
+
+## Error Handling
+
+### Common Errors
+
+```python
+from tools.errors import (
+    AuthenticationError,
+    AuthorizationError,
+    InvalidKeyError,
+    KeyExpiredError,
+    RateLimitError,
+    ValidationError
+)
+
+try:
+    key = key_manager.get_key("service")
+    if not key:
+        raise AuthenticationError("Invalid API key")
+
+    if not key.is_valid:
+        if key.is_expired:
+            raise KeyExpiredError(f"Key expired on {key.expires_at}")
+        raise InvalidKeyError("Key is inactive")
+
+    wait_time = await key_manager.check_rate_limit("service")
+    if wait_time > 0:
+        raise RateLimitError(
+            "Rate limit exceeded",
+            wait_time=wait_time
+        )
+except SecurityError as e:
+    print(f"Security error: [{e.code}] {e.message}")
+```
+
+### Error Recovery
+
+```python
+async def make_api_request():
+    try:
+        wait_time = await key_manager.check_rate_limit("service")
+        if wait_time > 0:
+            # Handle rate limiting gracefully
+            await asyncio.sleep(wait_time)
+            return await make_api_request()  # Retry after waiting
+
+        # Make request...
+    except RateLimitError as e:
+        logger.warning(f"Rate limited for {e.wait_time}s")
+        await asyncio.sleep(e.wait_time)
+        return await make_api_request()  # Retry after waiting
+    except KeyExpiredError:
+        # Rotate to new key
+        new_config = await key_manager.rotate_key(
+            name="service",
+            new_key=generate_new_key()
+        )
+        return await make_api_request()  # Retry with new key
+```
+
+## Best Practices
+
+1. **Key Rotation**
+   - Rotate keys regularly (e.g., every 90 days)
+   - Use expiration dates to enforce rotation
+   - Keep old keys active briefly during rotation
+
+2. **Rate Limiting**
+   - Set appropriate rate limits for your use case
+   - Use burst limits for handling traffic spikes
+   - Implement graceful backoff when rate limited
+
+3. **Error Handling**
+   - Always catch and handle security errors
+   - Log security events appropriately
+   - Implement retry logic with backoff
+
+4. **Validation**
+   - Validate all inputs before use
+   - Use appropriate scopes for access control
+   - Regularly audit active keys
+
+5. **Security**
+   - Store encryption keys securely
+   - Use environment variables for sensitive data
+   - Monitor and log security events
+
+## Examples
+
+### Complete Service Example
+
+```python
+from datetime import datetime, timezone, timedelta
+from tools.security import KeyManager
+from tools.errors import SecurityError
+
+class APIService:
+    def __init__(self):
+        self.key_manager = KeyManager(
+            keys_file="keys.json",
+            env_prefix="API"
+        )
+
+    async def initialize(self):
+        # Create service key if not exists
+        if not self.key_manager.get_key("service"):
+            await self.create_service_key()
+
+    async def create_service_key(self):
+        return self.key_manager.add_key(
+            name="service",
+            key=generate_secure_key(),
+            scopes=["read:data", "write:data"],
+            expires_at=datetime.now(timezone.utc) + timedelta(days=90),
+            rate_limit=10.0,
+            burst_limit=20
+        )
+
+    async def make_request(self, endpoint: str, data: dict):
+        try:
+            # Get and validate key
+            key = self.key_manager.get_key("service")
+            if not key:
+                raise AuthenticationError("Invalid API key")
+
+            if not key.is_valid:
+                if key.is_expired:
+                    # Rotate expired key
+                    key = await self.rotate_service_key()
+                else:
+                    raise InvalidKeyError("Key is inactive")
+
+            # Check rate limit
+            wait_time = await self.key_manager.check_rate_limit("service")
+            if wait_time > 0:
+                await asyncio.sleep(wait_time)
+
+            # Make request...
+            return await self._do_request(endpoint, data, key)
+
+        except RateLimitError as e:
+            logger.warning(f"Rate limited for {e.wait_time}s")
+            await asyncio.sleep(e.wait_time)
+            return await self.make_request(endpoint, data)
+
+        except KeyExpiredError:
+            logger.info("Rotating expired key")
+            await self.rotate_service_key()
+            return await self.make_request(endpoint, data)
+
+        except SecurityError as e:
+            logger.error(f"Security error: [{e.code}] {e.message}")
+            raise
+
+    async def rotate_service_key(self):
+        return self.key_manager.rotate_key(
+            name="service",
+            new_key=generate_secure_key(),
+            expires_at=datetime.now(timezone.utc) + timedelta(days=90)
+        )
+```
+
+### Batch Processing Example
+
+```python
+async def process_batch(items: list):
+    async with APIClient(
+        base_url="https://api.example.com",
+        rate_limit=50.0,
+        burst_limit=100
+    ) as client:
+        try:
+            results = await client.batch_request(
+                method="POST",
+                endpoint="/batch",
+                items=items
+            )
+            return results
+        except RateLimitError as e:
+            logger.warning(f"Batch rate limited for {e.wait_time}s")
+            # Split batch and retry with smaller chunks
+            mid = len(items) // 2
+            results1 = await process_batch(items[:mid])
+            results2 = await process_batch(items[mid:])
+            return results1 + results2
+```
+
+For more detailed information, refer to:
+- [API Documentation](api.md)
+- [Security Guide](security_quickstart.md)
+- [Error Handling Guide](errors.md)

prompts.yaml

@@ -319,3 +319,18 @@
   "report": |-
     Here is the final answer from your managed agent '{{name}}':
     {{final_answer}}
+
+system: |
+  You are an AI assistant that helps users with various tasks.
+  You have access to several tools including weather information, timezone conversion, and more.
+  Always be helpful, professional, and provide clear explanations in your responses.
+
+user: |
+  {input}
+
+assistant: |
+  I'll help you with your request: {output}
+
+error: |
+  I apologize, but I encountered an error: {error}
+  Please try again or rephrase your request.

pyproject.toml

@@ -0,0 +1,107 @@
+[tool.black]
+line-length = 100
+target-version = ['py39']
+include = '\.pyi?$'
+extend-exclude = '''
+# A regex preceded with ^/ will apply only to files and directories
+# in the root of the project.
+^/tests/data/
+'''
+
+[tool.isort]
+profile = "black"
+multi_line_output = 3
+include_trailing_comma = true
+force_grid_wrap = 0
+use_parentheses = true
+ensure_newline_before_comments = true
+line_length = 100
+skip_gitignore = true
+skip_glob = ["tests/data/*"]
+
+[tool.pylint.messages_control]
+disable = [
+    "C0111",  # missing-docstring
+    "C0103",  # invalid-name
+    "C0330",  # bad-continuation
+    "C0326",  # bad-whitespace
+    "W0621",  # redefined-outer-name
+    "W0614",  # unused-wildcard-import
+    "R0903",  # too-few-public-methods
+    "R0913",  # too-many-arguments
+    "R0914",  # too-many-locals
+]
+
+[tool.pylint.format]
+max-line-length = 100
+
+[tool.pylint.basic]
+good-names = ["i", "j", "k", "ex", "Run", "_", "fp", "id"]
+
+[tool.pylint.design]
+max-args = 8
+max-attributes = 12
+max-bool-expr = 5
+max-branches = 12
+max-locals = 20
+max-parents = 7
+max-public-methods = 20
+max-returns = 6
+max-statements = 50
+min-public-methods = 1
+
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = false
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_unreachable = true
+strict_equality = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+disallow_incomplete_defs = false
+
+[tool.pytest.ini_options]
+minversion = "6.0"
+addopts = "-ra -q --cov=tools --cov-report=term-missing"
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "integration: marks tests as integration tests",
+]
+
+[tool.bandit]
+exclude_dirs = ["tests", "venv", ".env", ".venv"]
+skips = ["B101", "B404", "B603"]
+targets = ["tools"]
+
+[tool.bandit.assert_used]
+skips = ["*_test.py", "*/test_*.py"]
+
+# Security settings
+[tool.bandit.any_other_function_with_shell_equals_true]
+no_shell = [
+    "subprocess.Popen",
+    "subprocess.run",
+    "subprocess.call",
+    "subprocess.check_call",
+    "subprocess.check_output",
+]
+
+[tool.bandit.hardcoded_tmp_directory]
+tmp_dirs = ["/tmp", "/var/tmp", "/dev/shm"]
+
+[tool.bandit.hardcoded_password_string]
+possible_strings = ["password", "pass", "pwd", "secret", "token"] 

pytest.ini

@@ -0,0 +1,45 @@
+[pytest]
+testpaths = tests
+python_files = test_*.py
+python_classes = Test*
+python_functions = test_*
+
+# Coverage settings
+addopts = 
+    --cov=tools
+    --cov-report=term-missing
+    --cov-report=html
+    --cov-report=xml
+    --cov-branch
+    --no-cov-on-fail
+
+# Coverage configuration
+[coverage:run]
+branch = True
+source = tools
+omit = 
+    */__init__.py
+    */tests/*
+    */venv/*
+    setup.py
+
+[coverage:report]
+exclude_lines =
+    pragma: no cover
+    def __repr__
+    raise NotImplementedError
+    if __name__ == .__main__.:
+    pass
+    raise ImportError
+    except ImportError:
+    if TYPE_CHECKING:
+
+show_missing = True
+skip_covered = False
+fail_under = 90
+
+[coverage:html]
+directory = coverage_html
+
+[coverage:xml]
+output = coverage.xml 

rate_limiter.py

@@ -0,0 +1,32 @@
+"""
+Rate limiter implementation using token bucket algorithm.
+"""
+import time
+from collections import defaultdict
+from typing import Dict, Tuple
+import logging
+
+logger = logging.getLogger(__name__)
+
+class RateLimiter:
+    def __init__(self, requests_per_minute: int):
+        self.requests_per_minute = requests_per_minute
+        self.tokens = requests_per_minute
+        self.last_update = time.time()
+    
+    def _add_tokens(self) -> None:
+        now = time.time()
+        time_passed = now - self.last_update
+        new_tokens = time_passed * (self.requests_per_minute / 60.0)
+        self.tokens = min(self.requests_per_minute, self.tokens + new_tokens)
+        self.last_update = now
+    
+    def acquire(self) -> bool:
+        self._add_tokens()
+        if self.tokens >= 1:
+            self.tokens -= 1
+            return True
+        return False
+
+# Global rate limiters
+rate_limiters: Dict[str, RateLimiter] = {} 

requirements.txt

@@ -1,7 +1,47 @@
-markdownify
-smolagents
-requests
-duckduckgo_search
-pandas
-smartystreets_python_sdk
-python-dotenv
+# Core dependencies
+requests>=2.31.0,<3.0.0
+python-dateutil>=2.8.2,<3.0.0
+pytz>=2024.1
+typing-extensions>=4.8.0
+pydantic>=2.0.0
+
+# API and HTTP
+aiohttp>=3.8.0
+urllib3>=2.2.0,<3.0.0  # Required by requests
+certifi>=2024.2.2  # For SSL certificates
+
+# Logging and monitoring
+structlog>=23.0.0,<25.0.0  # For structured logging
+python-json-logger>=2.0.7,<3.0.0  # JSON log formatting
+
+# Security
+python-jose[cryptography]>=3.3.0
+passlib[bcrypt]>=1.7.4
+python-dotenv>=0.19.0
+
+# UI
+gradio>=4.16.0,<5.0.0  # For web interface
+markdown>=3.5.2,<4.0.0  # For markdown rendering
+
+# Caching
+cachetools>=5.0.0
+
+# Error handling
+backoff>=2.2.1
+tenacity>=8.0.0
+
+# System monitoring
+psutil>=5.9.0,<6.0.0  # System resource monitoring
+
+# For testing
+pytest>=7.0.0
+pytest-asyncio>=0.21.0
+aioresponses>=0.7.5
+pytest-aiohttp>=1.0.5
+
+# Additional dependencies
+fastapi>=0.68.0
+uvicorn>=0.15.0
+python-multipart>=0.0.5
+httpx>=0.24.0
+cryptography>=41.0.0

scripts/run_tests.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""
+Script to run tests with coverage reporting.
+"""
+
+import os
+import sys
+import subprocess
+from typing import List, Optional
+
+def run_tests(args: Optional[List[str]] = None) -> int:
+    """
+    Run tests with coverage reporting.
+    
+    Args:
+        args: Additional pytest arguments.
+    
+    Returns:
+        Exit code from pytest.
+    """
+    # Ensure we're in the project root directory
+    project_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    os.chdir(project_root)
+    
+    # Base pytest command with coverage
+    cmd = [
+        "pytest",
+        "--verbose",
+        "--cov=tools",
+        "--cov-report=term-missing",
+        "--cov-report=html",
+        "--cov-report=xml",
+        "--cov-branch",
+    ]
+    
+    # Add any additional arguments
+    if args:
+        cmd.extend(args)
+    
+    # Run tests
+    try:
+        result = subprocess.run(cmd, check=True)
+        return result.returncode
+    except subprocess.CalledProcessError as e:
+        print(f"Error running tests: {e}", file=sys.stderr)
+        return e.returncode
+
+def print_coverage_report() -> None:
+    """Print a summary of the coverage report."""
+    try:
+        # Read the coverage XML report
+        import xml.etree.ElementTree as ET
+        tree = ET.parse('coverage.xml')
+        root = tree.getroot()
+        
+        # Get overall coverage metrics
+        metrics = root.find('.//metrics')
+        if metrics is not None:
+            statements = int(metrics.get('statements', 0))
+            covered = int(metrics.get('covered', 0))
+            branches = int(metrics.get('branches', 0))
+            branches_covered = int(metrics.get('branches-covered', 0))
+            
+            # Calculate percentages
+            line_coverage = (covered / statements * 100) if statements else 0
+            branch_coverage = (branches_covered / branches * 100) if branches else 0
+            
+            print("\nCoverage Summary:")
+            print(f"Line Coverage: {line_coverage:.1f}%")
+            print(f"Branch Coverage: {branch_coverage:.1f}%")
+            print(f"Statements: {covered}/{statements}")
+            print(f"Branches: {branches_covered}/{branches}")
+            
+            # Print location of detailed reports
+            print("\nDetailed reports generated:")
+            print("- HTML report: coverage_html/index.html")
+            print("- XML report: coverage.xml")
+    except Exception as e:
+        print(f"Error reading coverage report: {e}", file=sys.stderr)
+
+def main() -> int:
+    """Main entry point."""
+    # Get any additional arguments
+    args = sys.argv[1:] if len(sys.argv) > 1 else None
+    
+    # Run tests
+    result = run_tests(args)
+    
+    # Print coverage summary if tests passed
+    if result == 0:
+        print_coverage_report()
+    
+    return result
+
+if __name__ == "__main__":
+    sys.exit(main()) 

setup.py

@@ -0,0 +1,148 @@
+"""
+Setup configuration for the AI Assistant package.
+"""
+
+import os
+from setuptools import setup, find_packages
+
+# Read the contents of README.md
+with open("README.md", encoding="utf-8") as f:
+    long_description = f.read()
+
+# Read the contents of requirements.txt
+with open("requirements.txt", encoding="utf-8") as f:
+    requirements = [
+        line.strip()
+        for line in f
+        if line.strip() and not line.startswith("#") and not line.startswith("-")
+    ]
+
+# Package metadata
+NAME = "ai-assistant"
+DESCRIPTION = "A robust framework for building AI assistants with built-in error handling, logging, and API integration capabilities"
+AUTHOR = "Your Name"
+AUTHOR_EMAIL = "your.email@example.com"
+URL = "https://github.com/yourusername/ai-assistant"
+LICENSE = "MIT"
+PYTHON_REQUIRES = ">=3.9"
+VERSION = "0.1.0"  # Also update in __init__.py
+
+# Classifiers help users find your project
+CLASSIFIERS = [
+    # Development Status
+    "Development Status :: 4 - Beta",
+    
+    # Intended Audience
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    
+    # License
+    "License :: OSI Approved :: MIT License",
+    
+    # Python versions
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    
+    # Environment
+    "Operating System :: OS Independent",
+    
+    # Topics
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    
+    # Typing
+    "Typing :: Typed",
+]
+
+# Additional package data
+PACKAGE_DATA = {
+    "ai_assistant": [
+        "py.typed",  # Marker file for PEP 561
+        "prompts/*.yaml",  # Include prompt templates
+        "config/*.json",  # Include default configurations
+    ]
+}
+
+setup(
+    # Basic package information
+    name=NAME,
+    version=VERSION,
+    description=DESCRIPTION,
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    
+    # Author information
+    author=AUTHOR,
+    author_email=AUTHOR_EMAIL,
+    
+    # Project URLs
+    url=URL,
+    project_urls={
+        "Bug Tracker": f"{URL}/issues",
+        "Documentation": f"{URL}/docs",
+        "Source Code": URL,
+    },
+    
+    # License and Python version
+    license=LICENSE,
+    python_requires=PYTHON_REQUIRES,
+    
+    # Package configuration
+    packages=find_packages(exclude=["tests*", "docs*"]),
+    package_data=PACKAGE_DATA,
+    include_package_data=True,
+    zip_safe=False,  # Required for mypy to find py.typed
+    
+    # Dependencies
+    install_requires=requirements,
+    extras_require={
+        "dev": [
+            line.strip()
+            for line in open("requirements-dev.txt")
+            if line.strip() and not line.startswith("#") and not line.startswith("-")
+        ],
+        "docs": [
+            "sphinx>=7.2.6,<8.0.0",
+            "sphinx-rtd-theme>=2.0.0,<3.0.0",
+            "sphinx-autodoc-typehints>=1.25.2,<2.0.0",
+            "sphinx-copybutton>=0.5.2,<1.0.0",
+            "myst-parser>=2.0.0,<3.0.0",
+        ],
+        "test": [
+            "pytest>=8.0.0,<9.0.0",
+            "pytest-cov>=4.1.0,<5.0.0",
+            "pytest-asyncio>=0.23.5,<1.0.0",
+            "pytest-mock>=3.12.0,<4.0.0",
+            "responses>=0.24.1,<1.0.0",
+            "freezegun>=1.4.0,<2.0.0",
+            "faker>=22.6.0,<23.0.0",
+        ],
+    },
+    
+    # Entry points for CLI tools
+    entry_points={
+        "console_scripts": [
+            "ai-assistant=tools.cli:main",
+        ],
+    },
+    
+    # Classifiers
+    classifiers=CLASSIFIERS,
+    
+    # Keywords for PyPI
+    keywords=[
+        "ai",
+        "assistant",
+        "nlp",
+        "machine-learning",
+        "api",
+        "tools",
+        "automation",
+        "error-handling",
+        "logging",
+    ],
+) 

test_app.py

@@ -0,0 +1,124 @@
+"""Tests for the API key management web interface."""
+
+import pytest
+from fastapi.testclient import TestClient
+from datetime import datetime, timezone
+
+from app import app
+
+client = TestClient(app)
+
+def test_root():
+    """Test root endpoint."""
+    response = client.get("/")
+    assert response.status_code == 200
+    assert response.json()["message"] == "API Key Management System"
+
+def test_create_and_get_key():
+    """Test key creation and retrieval."""
+    # Create a key
+    create_response = client.post(
+        "/keys",
+        json={
+            "name": "test_service",
+            "scopes": ["read:data", "write:data"],
+            "rate_limit": 5.0,
+            "burst_limit": 10,
+            "expires_in_days": 90
+        }
+    )
+    assert create_response.status_code == 200
+    key_data = create_response.json()
+    assert key_data["name"] == "test_service"
+    assert key_data["scopes"] == ["read:data", "write:data"]
+    assert key_data["rate_limit"] == 5.0
+    assert key_data["burst_limit"] == 10
+    assert key_data["is_active"] is True
+
+    # Get the key
+    get_response = client.get(f"/keys/test_service")
+    assert get_response.status_code == 200
+    get_data = get_response.json()
+    assert get_data["name"] == "test_service"
+    assert get_data["scopes"] == ["read:data", "write:data"]
+    assert get_data["is_active"] is True
+
+def test_list_keys():
+    """Test listing keys."""
+    # Create a test key first
+    client.post(
+        "/keys",
+        json={
+            "name": "list_test_service",
+            "scopes": ["read:only"]
+        }
+    )
+
+    # List keys
+    response = client.get("/keys")
+    assert response.status_code == 200
+    keys = response.json()
+    assert "list_test_service" in keys
+    assert keys["list_test_service"]["scopes"] == ["read:only"]
+
+def test_rotate_key():
+    """Test key rotation."""
+    # Create a key first
+    client.post(
+        "/keys",
+        json={
+            "name": "rotate_test_service",
+            "scopes": ["read:data"]
+        }
+    )
+
+    # Rotate the key
+    rotate_response = client.post(
+        "/keys/rotate_test_service/rotate",
+        params={"expires_in_days": 30}
+    )
+    assert rotate_response.status_code == 200
+    rotated_key = rotate_response.json()
+    assert rotated_key["name"] == "rotate_test_service"
+    assert rotated_key["is_active"] is True
+
+def test_delete_key():
+    """Test key deletion."""
+    # Create a key first
+    client.post(
+        "/keys",
+        json={
+            "name": "delete_test_service",
+            "scopes": ["read:data"]
+        }
+    )
+
+    # Delete the key
+    delete_response = client.delete("/keys/delete_test_service")
+    assert delete_response.status_code == 200
+
+    # Verify key is gone
+    get_response = client.get("/keys/delete_test_service")
+    assert get_response.status_code == 404
+
+def test_invalid_key_creation():
+    """Test validation for key creation."""
+    response = client.post(
+        "/keys",
+        json={
+            "name": "invalid!name",  # Invalid character in name
+            "scopes": ["invalid:scope"],  # Invalid scope format
+            "rate_limit": -1.0,  # Invalid rate limit
+            "burst_limit": 0  # Invalid burst limit
+        }
+    )
+    assert response.status_code == 400
+
+def test_metrics():
+    """Test metrics endpoint."""
+    response = client.get("/metrics")
+    assert response.status_code == 200
+    metrics = response.json()
+    assert "latency" in metrics
+    assert "rate_limiting" in metrics
+    assert "connections" in metrics

tests/integration/test_assistant.py

@@ -0,0 +1,402 @@
+"""
+Integration tests for the AI Assistant.
+
+These tests verify that different tools work together correctly in common scenarios
+that the assistant might encounter.
+"""
+
+import pytest
+from datetime import datetime, timezone
+from typing import List, Dict, Any
+from unittest.mock import Mock, patch
+
+from tools.base import ToolRegistry
+from tools.timezone_tools import TimezoneTools
+from tools.final_answer import FinalAnswerTool
+from tools.exceptions import (
+    InvalidTimezoneError,
+    TimeFormatError,
+    ValidationError,
+    ToolNotFoundError
+)
+from tests.utils.mock_responses import (
+    MOCK_RESPONSES,
+    MOCK_ENDPOINTS,
+    create_mock_time_response,
+    create_mock_timezone_response,
+    create_mock_error_response
+)
+
+@pytest.fixture
+def registry() -> ToolRegistry:
+    """Fixture that provides a clean ToolRegistry instance with all tools registered."""
+    registry = ToolRegistry()
+    registry.clear()
+    # Register all tools that should be available to the assistant
+    registry.register(TimezoneTools)
+    registry.register(FinalAnswerTool)
+    return registry
+
+@pytest.fixture
+def mock_api_calls() -> None:
+    """Fixture that mocks all API calls."""
+    with patch('tools.timezone_tools.requests.get') as mock_get:
+        def mock_api_response(*args: Any, **kwargs: Any) -> Mock:
+            url = args[0]
+            if "time" in url:
+                timezone_param = kwargs.get('params', {}).get('timezone', 'UTC')
+                return MOCK_ENDPOINTS["time"].get(
+                    timezone_param,
+                    MOCK_RESPONSES["invalid_timezone"]
+                )
+            elif "timezone" in url:
+                timezone_name = url.split('/')[-1]
+                return MOCK_ENDPOINTS["timezone"].get(
+                    timezone_name,
+                    MOCK_RESPONSES["invalid_timezone"]
+                )
+            return MOCK_RESPONSES["invalid_timezone"]
+        
+        mock_get.side_effect = mock_api_response
+        yield mock_get
+
+class TestTimezoneFinalAnswerIntegration:
+    """Test integration between timezone and final answer tools."""
+    
+    def test_timezone_conversion_to_final_answer(
+        self,
+        registry: ToolRegistry,
+        mock_api_calls: Mock
+    ) -> None:
+        """Test converting time and formatting it as a final answer."""
+        # Get tool instances
+        tz_tool = registry.get_tool("timezone")
+        answer_tool = registry.get_tool("final_answer")
+        
+        # Convert time using timezone tool
+        time_str = "2024-01-01T12:00:00"
+        converted = tz_tool.convert_time(
+            time_str,
+            from_tz="UTC",
+            to_tz="America/New_York"
+        )
+        
+        # Format as final answer
+        answer = answer_tool.submit_answer(
+            answer=converted.strftime("%Y-%m-%d %H:%M:%S %Z"),
+            confidence=1.0,
+            source="Timezone conversion",
+            reasoning=f"Converted {time_str} from UTC to America/New_York"
+        )
+        
+        # Verify the answer and API calls
+        assert "2024-01-01 07:00:00" in answer
+        assert "America/New_York" in answer
+        assert "Confidence: 100%" in answer
+        mock_api_calls.assert_called()
+    
+    def test_multiple_timezone_conversions_to_final_answer(
+        self,
+        registry: ToolRegistry,
+        mock_api_calls: Mock
+    ) -> None:
+        """Test converting time to multiple zones and combining in final answer."""
+        tz_tool = registry.get_tool("timezone")
+        answer_tool = registry.get_tool("final_answer")
+        
+        # Convert current time to multiple zones
+        zones = ["UTC", "America/New_York", "Asia/Tokyo"]
+        times = []
+        for zone in zones:
+            time = tz_tool.get_current_time(zone)
+            times.append(f"{zone}: {time.strftime('%H:%M:%S %Z')}")
+        
+        # Combine results in final answer
+        answer = answer_tool.submit_answer(
+            answer="\n".join(times),
+            confidence=1.0,
+            source="Current time in multiple zones",
+            reasoning="Retrieved current time in UTC, New York, and Tokyo"
+        )
+        
+        # Verify the answer and API calls
+        for zone in zones:
+            assert zone in answer
+        assert "Confidence: 100%" in answer
+        assert mock_api_calls.call_count == len(zones)
+
+class TestErrorHandlingIntegration:
+    """Test error handling across multiple tools."""
+    
+    def test_invalid_timezone_to_final_answer(
+        self,
+        registry: ToolRegistry,
+        mock_api_calls: Mock
+    ) -> None:
+        """Test handling invalid timezone error in final answer."""
+        tz_tool = registry.get_tool("timezone")
+        answer_tool = registry.get_tool("final_answer")
+        
+        # Try to get time for invalid timezone
+        invalid_zone = "Invalid/Zone"
+        error_message = ""
+        try:
+            tz_tool.get_current_time(invalid_zone)
+        except InvalidTimezoneError as e:
+            error_message = str(e)
+        
+        # Report error in final answer
+        answer = answer_tool.submit_answer(
+            answer=f"Error: {error_message}",
+            confidence=1.0,
+            source="Timezone operation",
+            reasoning=f"Failed to get time for invalid timezone: {invalid_zone}"
+        )
+        
+        # Verify error handling and API calls
+        assert "Invalid timezone" in answer
+        assert invalid_zone in answer
+        assert "Error" in answer
+        mock_api_calls.assert_called_once()
+    
+    def test_rate_limit_handling(
+        self,
+        registry: ToolRegistry,
+        mock_api_calls: Mock
+    ) -> None:
+        """Test handling rate limit errors."""
+        mock_api_calls.side_effect = lambda *args, **kwargs: MOCK_RESPONSES["rate_limit"]
+        
+        tz_tool = registry.get_tool("timezone")
+        answer_tool = registry.get_tool("final_answer")
+        
+        try:
+            tz_tool.get_current_time("UTC")
+        except Exception as e:
+            error_message = str(e)
+        
+        answer = answer_tool.submit_answer(
+            answer=f"Error: {error_message}",
+            confidence=1.0,
+            source="Rate limit handling",
+            reasoning="API rate limit exceeded"
+        )
+        
+        assert "rate limit" in answer.lower()
+        assert "30" in error_message  # Retry-After value
+        mock_api_calls.assert_called_once()
+
+class TestToolRegistryIntegration:
+    """Test tool registry integration scenarios."""
+    
+    def test_tool_dependencies(
+        self,
+        registry: ToolRegistry,
+        mock_api_calls: Mock
+    ) -> None:
+        """Test tools that depend on other tools."""
+        class DependentTool(TimezoneTools):
+            def __init__(self) -> None:
+                super().__init__()
+                self._answer_tool = registry.get_tool("final_answer")
+            
+            @property
+            def name(self) -> str:
+                return "dependent_tool"
+            
+            def get_formatted_time(self, timezone_name: str) -> str:
+                """Get current time and format it using final answer tool."""
+                time = self.get_current_time(timezone_name)
+                return self._answer_tool.submit_answer(
+                    answer=time.strftime("%Y-%m-%d %H:%M:%S %Z"),
+                    confidence=1.0,
+                    source=f"Current time in {timezone_name}",
+                    reasoning=f"Retrieved current time for {timezone_name}"
+                )
+        
+        # Register and test dependent tool
+        registry.register(DependentTool)
+        dependent_tool = registry.get_tool("dependent_tool")
+        
+        result = dependent_tool.get_formatted_time("UTC")
+        assert "UTC" in result
+        assert "Confidence: 100%" in result
+        mock_api_calls.assert_called_once()
+    
+    def test_tool_chain(
+        self,
+        registry: ToolRegistry,
+        mock_api_calls: Mock
+    ) -> None:
+        """Test chaining multiple tools together."""
+        tz_tool = registry.get_tool("timezone")
+        answer_tool = registry.get_tool("final_answer")
+        
+        # Chain of operations:
+        # 1. Get current UTC time
+        # 2. Convert to NY time
+        # 3. Get timezone offset
+        # 4. Format as final answer
+        
+        utc_time = tz_tool.get_current_time("UTC")
+        ny_time = tz_tool.convert_time(utc_time, to_tz="America/New_York")
+        ny_offset = tz_tool.get_timezone_offset("America/New_York")
+        
+        answer = answer_tool.submit_answer(
+            answer=f"New York: {ny_time.strftime('%H:%M:%S')} ({ny_offset})",
+            confidence=1.0,
+            source="Time conversion chain",
+            reasoning=(
+                f"Converted current UTC time ({utc_time.strftime('%H:%M:%S')}) "
+                f"to New York time with offset {ny_offset}"
+            )
+        )
+        
+        # Verify chain results and API calls
+        assert "New York" in answer
+        assert ny_offset in answer
+        assert "UTC" in answer
+        assert "Confidence: 100%" in answer
+        assert mock_api_calls.call_count >= 3  # At least 3 API calls in the chain
+
+class TestErrorRecoveryIntegration:
+    """Test error recovery scenarios across tools."""
+    
+    def test_fallback_timezone_conversion(
+        self,
+        registry: ToolRegistry,
+        mock_api_calls: Mock
+    ) -> None:
+        """Test fallback to UTC when timezone conversion fails."""
+        tz_tool = registry.get_tool("timezone")
+        answer_tool = registry.get_tool("final_answer")
+        
+        time_str = "2024-01-01T12:00:00"
+        target_zone = "Invalid/Zone"
+        
+        # First call will fail, second call to UTC will succeed
+        mock_api_calls.side_effect = [
+            MOCK_RESPONSES["invalid_timezone"],
+            MOCK_RESPONSES["utc_time"]
+        ]
+        
+        try:
+            # Try to convert to invalid timezone
+            converted = tz_tool.convert_time(time_str, to_tz=target_zone)
+        except InvalidTimezoneError:
+            # Fallback to UTC
+            converted = tz_tool.convert_time(time_str, to_tz="UTC")
+            
+            answer = answer_tool.submit_answer(
+                answer=converted.strftime("%Y-%m-%d %H:%M:%S %Z"),
+                confidence=0.8,  # Lower confidence due to fallback
+                source="Timezone conversion with fallback",
+                reasoning=(
+                    f"Failed to convert to {target_zone}, "
+                    f"falling back to UTC time"
+                )
+            )
+        
+        # Verify fallback behavior and API calls
+        assert "UTC" in answer
+        assert "Confidence: 80%" in answer
+        assert "falling back to UTC" in answer.lower()
+        assert mock_api_calls.call_count == 2
+    
+    def test_graceful_degradation(
+        self,
+        registry: ToolRegistry,
+        mock_api_calls: Mock
+    ) -> None:
+        """Test graceful degradation when some operations fail."""
+        tz_tool = registry.get_tool("timezone")
+        answer_tool = registry.get_tool("final_answer")
+        
+        # Configure mock to alternate between success and failure
+        mock_api_calls.side_effect = [
+            MOCK_RESPONSES["utc_time"],
+            MOCK_RESPONSES["invalid_timezone"],
+            MOCK_RESPONSES["ny_time"],
+            MOCK_RESPONSES["invalid_timezone"]
+        ]
+        
+        # Try to perform multiple operations, some of which will fail
+        results = []
+        zones = ["UTC", "Invalid/Zone1", "America/New_York", "Invalid/Zone2"]
+        
+        for zone in zones:
+            try:
+                time = tz_tool.get_current_time(zone)
+                results.append(f"{zone}: {time.strftime('%H:%M:%S %Z')}")
+            except InvalidTimezoneError:
+                results.append(f"{zone}: Invalid timezone")
+        
+        # Report partial results
+        answer = answer_tool.submit_answer(
+            answer="\n".join(results),
+            confidence=0.7,  # Lower confidence due to partial failure
+            source="Multi-timezone operation with errors",
+            reasoning="Some timezone operations failed, reporting partial results"
+        )
+        
+        # Verify partial results handling and API calls
+        assert "UTC" in answer
+        assert "America/New_York" in answer
+        assert "Invalid timezone" in answer
+        assert "Confidence: 70%" in answer
+        assert "partial results" in answer.lower()
+        assert mock_api_calls.call_count == 4
+
+class TestConcurrentToolUsage:
+    """Test using multiple tools concurrently."""
+    
+    def test_parallel_timezone_queries(
+        self,
+        registry: ToolRegistry,
+        mock_api_calls: Mock
+    ) -> None:
+        """Test querying multiple timezones in parallel."""
+        import concurrent.futures
+        
+        tz_tool = registry.get_tool("timezone")
+        answer_tool = registry.get_tool("final_answer")
+        
+        zones = [
+            "UTC",
+            "America/New_York",
+            "Europe/London",
+            "Asia/Tokyo",
+            "Australia/Sydney"
+        ]
+        
+        def get_zone_time(zone: str) -> str:
+            time = tz_tool.get_current_time(zone)
+            return f"{zone}: {time.strftime('%H:%M:%S %Z')}"
+        
+        # Configure mock responses for parallel calls
+        mock_api_calls.side_effect = [
+            MOCK_RESPONSES["utc_time"],
+            MOCK_RESPONSES["ny_time"],
+            create_mock_time_response("2024-01-01T12:00:00Z", "Europe/London"),
+            MOCK_RESPONSES["tokyo_time"],
+            create_mock_time_response("2024-01-01T23:00:00Z", "Australia/Sydney")
+        ]
+        
+        # Get times in parallel
+        with concurrent.futures.ThreadPoolExecutor() as executor:
+            futures = [executor.submit(get_zone_time, zone) for zone in zones]
+            results = [f.result() for f in futures]
+        
+        # Combine results
+        answer = answer_tool.submit_answer(
+            answer="\n".join(results),
+            confidence=1.0,
+            source="Parallel timezone queries",
+            reasoning="Retrieved current time for multiple zones concurrently"
+        )
+        
+        # Verify parallel execution results and API calls
+        for zone in zones:
+            assert zone in answer
+        assert "Confidence: 100%" in answer
+        assert mock_api_calls.call_count == len(zones) 

tests/test_api_logging.py

@@ -0,0 +1,220 @@
+"""
+Tests for the API logging functionality.
+"""
+
+from datetime import datetime
+import json
+import logging
+from typing import Dict, Any, List
+import pytest
+from unittest.mock import Mock, patch
+
+from tools.api_logging import log_api_call, sanitize_headers, sanitize_url
+from tools.exceptions import APIError, APIRateLimitError, APITimeoutError
+from tools.error_recovery import RetryConfig, CircuitBreaker
+
+# Test data
+TEST_URL = "https://api.example.com/v1/data?api_key=secret123&format=json"
+TEST_HEADERS = {
+    "Authorization": "Bearer token123",
+    "Content-Type": "application/json",
+    "X-API-Key": "secret456"
+}
+TEST_REQUEST_BODY = {
+    "query": "test",
+    "limit": 10
+}
+
+def test_sanitize_headers() -> None:
+    """Test sanitization of headers."""
+    sanitized = sanitize_headers(TEST_HEADERS)
+    assert sanitized["Authorization"] == "****"
+    assert sanitized["Content-Type"] == "application/json"
+    assert sanitized["X-API-Key"] == "****"
+
+def test_sanitize_url() -> None:
+    """Test sanitization of URLs."""
+    sanitized = sanitize_url(TEST_URL)
+    assert "api_key=****" in sanitized
+    assert "secret123" not in sanitized
+    assert "format=json" in sanitized
+
+@pytest.fixture
+def mock_logger() -> Mock:
+    """Fixture that provides a mock logger."""
+    with patch('tools.api_logging.logger') as mock_log:
+        yield mock_log
+
+def test_successful_api_call(mock_logger: Mock) -> None:
+    """Test logging of successful API calls."""
+    
+    @log_api_call
+    def mock_api_call(url: str, headers: Dict[str, str], json: Dict[str, Any]) -> Mock:
+        response = Mock()
+        response.status_code = 200
+        response.json.return_value = {"status": "success"}
+        return response
+
+    response = mock_api_call(TEST_URL, headers=TEST_HEADERS, json=TEST_REQUEST_BODY)
+    
+    # Check request logging
+    request_call = mock_logger.info.call_args_list[0]
+    request_log = json.loads(request_call.args[0].replace("API Request: ", ""))
+    assert "timestamp" in request_log
+    assert request_log["function"] == "mock_api_call"
+    assert "api_key=****" in request_log["url"]
+    assert request_log["headers"]["Authorization"] == "****"
+    
+    # Check response logging
+    response_call = mock_logger.info.call_args_list[1]
+    response_log = json.loads(response_call.args[0].replace("API Response: ", ""))
+    assert response_log["status"] == 200
+    assert response_log["body"] == {"status": "success"}
+
+def test_api_call_with_retry(mock_logger: Mock) -> None:
+    """Test API call with retry configuration."""
+    attempts = 0
+    
+    @log_api_call(
+        retry_config=RetryConfig(max_retries=2, initial_delay=0.01),
+        circuit_breaker=CircuitBreaker(failure_threshold=3)
+    )
+    def failing_then_succeeding(url: str) -> Mock:
+        nonlocal attempts
+        attempts += 1
+        if attempts < 2:
+            raise TimeoutError("Connection timeout")
+        response = Mock()
+        response.status_code = 200
+        response.json.return_value = {"status": "success"}
+        return response
+
+    response = failing_then_succeeding(TEST_URL)
+    
+    # Should have logged initial failure and final success
+    assert attempts == 2
+    assert len(mock_logger.info.call_args_list) == 4  # 2 requests + 2 responses
+    assert len(mock_logger.error.call_args_list) == 1  # 1 error
+    
+    # Check final response
+    assert response.status_code == 200
+    assert response.json() == {"status": "success"}
+
+def test_api_call_with_circuit_breaker(mock_logger: Mock) -> None:
+    """Test API call with circuit breaker."""
+    attempts = 0
+    cb = CircuitBreaker(failure_threshold=2, reset_timeout=0.1)
+    
+    @log_api_call(circuit_breaker=cb)
+    def always_failing(url: str) -> None:
+        nonlocal attempts
+        attempts += 1
+        raise ConnectionError("Connection failed")
+
+    # First call should fail normally
+    with pytest.raises(APIError):
+        always_failing(TEST_URL)
+    assert attempts == 1
+    
+    # Second call should fail and open the circuit
+    with pytest.raises(APIError):
+        always_failing(TEST_URL)
+    assert attempts == 2
+    
+    # Third call should fail immediately with circuit breaker error
+    with pytest.raises(APIError) as exc_info:
+        always_failing(TEST_URL)
+    assert attempts == 2  # No additional attempt
+    assert "Circuit breaker is open" in str(exc_info.value)
+
+def test_api_call_with_rate_limit_retry(mock_logger: Mock) -> None:
+    """Test API call with rate limit retry."""
+    attempts = 0
+    
+    @log_api_call(
+        retry_config=RetryConfig(max_retries=1, initial_delay=0.01)
+    )
+    def rate_limited(url: str) -> None:
+        nonlocal attempts
+        attempts += 1
+        response = Mock()
+        response.status_code = 429
+        response.headers = {"Retry-After": "0.1"}
+        error = Exception("Rate limit exceeded")
+        error.response = response
+        raise error
+
+    with pytest.raises(APIRateLimitError) as exc_info:
+        rate_limited(TEST_URL)
+    
+    assert attempts == 2  # Initial + 1 retry
+    error = exc_info.value
+    assert error.retry_after == 0.1
+    assert "rate limit exceeded" in str(error).lower()
+
+def test_api_call_with_non_json_response(mock_logger: Mock) -> None:
+    """Test API call with non-JSON response."""
+    
+    @log_api_call
+    def text_response(url: str) -> Mock:
+        response = Mock()
+        response.status_code = 200
+        response.json.side_effect = ValueError("Invalid JSON")
+        response.__str__ = lambda self: "Plain text response"
+        return response
+
+    response = text_response(TEST_URL)
+    
+    # Check response logging
+    response_call = mock_logger.info.call_args_list[1]
+    response_log = json.loads(response_call.args[0].replace("API Response: ", ""))
+    assert response_log["status"] == 200
+    assert response_log["body"] == "Plain text response"
+
+def test_api_call_with_custom_retry_conditions(mock_logger: Mock) -> None:
+    """Test API call with custom retry conditions."""
+    attempts = 0
+    
+    class CustomError(Exception):
+        pass
+    
+    retry_config = RetryConfig(
+        max_retries=2,
+        initial_delay=0.01,
+        retry_on={CustomError, APITimeoutError}
+    )
+    
+    @log_api_call(retry_config=retry_config)
+    def custom_error(url: str) -> None:
+        nonlocal attempts
+        attempts += 1
+        raise CustomError("Custom error")
+
+    with pytest.raises(APIError):
+        custom_error(TEST_URL)
+    
+    assert attempts == 3  # Initial + 2 retries
+
+def test_api_call_logs_sanitized_data(mock_logger: Mock) -> None:
+    """Test that API call logs are properly sanitized."""
+    sensitive_data = {
+        "api_key": "secret123",
+        "password": "sensitive",
+        "query": "safe_data"
+    }
+    
+    @log_api_call(log_request_body=True)
+    def sensitive_call(url: str, json: Dict[str, Any]) -> Mock:
+        response = Mock()
+        response.status_code = 200
+        response.json.return_value = {"status": "success"}
+        return response
+
+    sensitive_call(TEST_URL, json=sensitive_data)
+    
+    # Check request logging
+    request_call = mock_logger.info.call_args_list[0]
+    request_log = json.loads(request_call.args[0].replace("API Request: ", ""))
+    log_body = json.loads(request_log["body"])
+    assert log_body["api_key"] == "secret123"  # Body content isn't sanitized
+    assert "api_key=****" in request_log["url"]  # URL is sanitized 

tests/test_api_optimization.py

@@ -0,0 +1,209 @@
+"""Tests for API optimization utilities."""
+
+import asyncio
+from datetime import timedelta
+from typing import Any, Dict, List
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import aiohttp
+import pytest
+from aioresponses import aioresponses
+
+from tools.api_optimization import (
+    APIClient,
+    BatchProcessor,
+    ConnectionPool,
+    RateLimiter,
+    with_rate_limit,
+    with_retry,
+)
+
+@pytest.fixture
+def rate_limiter() -> RateLimiter:
+    """Create a test rate limiter."""
+    return RateLimiter(rate=10.0, burst=20)
+
+@pytest.fixture
+def batch_processor() -> BatchProcessor:
+    """Create a test batch processor."""
+    return BatchProcessor(batch_size=2, flush_interval=0.1)
+
+@pytest.fixture
+def connection_pool() -> ConnectionPool:
+    """Create a test connection pool."""
+    return ConnectionPool(pool_size=2, timeout=1.0)
+
+@pytest.fixture
+def api_client() -> APIClient:
+    """Create a test API client."""
+    return APIClient(
+        base_url="http://test.api",
+        pool_size=2,
+        rate_limit=10.0,
+        burst_limit=20,
+        batch_size=2
+    )
+
+async def test_rate_limiter(rate_limiter: RateLimiter):
+    """Test rate limiter functionality."""
+    # Test initial state
+    assert rate_limiter.tokens == rate_limiter.burst
+
+    # Test token acquisition
+    wait_time = rate_limiter.acquire(1.0)
+    assert wait_time == 0.0
+    assert rate_limiter.tokens == rate_limiter.burst - 1
+
+    # Test burst handling
+    wait_time = rate_limiter.acquire(rate_limiter.burst)
+    assert wait_time > 0.0
+    assert rate_limiter.tokens == 0.0
+
+async def test_batch_processor(batch_processor: BatchProcessor):
+    """Test batch processor functionality."""
+    # Test batch accumulation
+    await batch_processor.add({"key": "value1"})
+    assert len(batch_processor.batch) == 1
+
+    # Test batch flush on size
+    await batch_processor.add({"key": "value2"})
+    assert len(batch_processor.batch) == 0
+
+    # Test batch flush on interval
+    await batch_processor.add({"key": "value3"})
+    await asyncio.sleep(0.2)  # Wait for flush interval
+    assert len(batch_processor.batch) == 0
+
+async def test_connection_pool():
+    """Test connection pool functionality."""
+    pool = ConnectionPool(pool_size=2)
+
+    async with pool as p:
+        assert isinstance(p, ConnectionPool)
+        assert p.session is not None
+
+        with aioresponses() as mocked:
+            url = "http://test.api/endpoint"
+            mocked.get(url, status=200, payload={"key": "value"})
+
+            response = await p.request("GET", url)
+            assert response.status == 200
+
+async def test_retry_decorator():
+    """Test retry decorator functionality."""
+    mock_func = AsyncMock(side_effect=[Exception, Exception, "success"])
+
+    @with_retry(max_attempts=3, min_wait=0.1, max_wait=0.3)
+    async def test_func():
+        return await mock_func()
+
+    result = await test_func()
+    assert result == "success"
+    assert mock_func.call_count == 3
+
+async def test_rate_limit_decorator():
+    """Test rate limit decorator functionality."""
+    call_times: List[float] = []
+
+    @with_rate_limit(rate=10.0, burst=2)
+    async def test_func():
+        call_times.append(asyncio.get_event_loop().time())
+
+    # Make multiple calls
+    await asyncio.gather(*[test_func() for _ in range(3)])
+
+    # Verify rate limiting
+    time_diffs = [
+        call_times[i] - call_times[i-1]
+        for i in range(1, len(call_times))
+    ]
+    assert all(diff >= 0.1 for diff in time_diffs)  # At least 0.1s between calls
+
+async def test_api_client(api_client: APIClient):
+    """Test API client functionality."""
+    with aioresponses() as mocked:
+        # Test single request
+        url = "http://test.api/test"
+        mocked.post(url, status=200, payload={"result": "success"})
+
+        response = await api_client.request(
+            "POST",
+            "test",
+            json={"data": "test"}
+        )
+        assert response == {"result": "success"}
+
+        # Test batch request
+        items = [
+            {"id": 1, "data": "test1"},
+            {"id": 2, "data": "test2"}
+        ]
+        mocked.post(url, repeat=True, status=200, payload={"result": "success"})
+
+        results = await api_client.batch_request("POST", "test", items)
+        assert len(results) == 2
+        assert all(r == {"result": "success"} for r in results)
+
+async def test_api_client_error_handling(api_client: APIClient):
+    """Test API client error handling."""
+    with aioresponses() as mocked:
+        url = "http://test.api/test"
+
+        # Test retry on error
+        mocked.post(
+            url,
+            status=500,
+            repeat=True,
+            exception=aiohttp.ClientError()
+        )
+
+        with pytest.raises(aiohttp.ClientError):
+            await api_client.request("POST", "test", json={"data": "test"})
+
+async def test_api_client_rate_limiting(api_client: APIClient):
+    """Test API client rate limiting."""
+    with aioresponses() as mocked:
+        url = "http://test.api/test"
+        mocked.post(
+            url,
+            status=200,
+            payload={"result": "success"},
+            repeat=True
+        )
+
+        start_time = asyncio.get_event_loop().time()
+
+        # Make multiple requests
+        responses = await asyncio.gather(*[
+            api_client.request("POST", "test", json={"data": f"test{i}"})
+            for i in range(5)
+        ])
+
+        end_time = asyncio.get_event_loop().time()
+        duration = end_time - start_time
+
+        # Verify rate limiting
+        assert duration >= 0.4  # At least 0.4s for 5 requests at 10 RPS
+        assert all(r == {"result": "success"} for r in responses)
+
+async def test_connection_pool_limits(api_client: APIClient):
+    """Test connection pool concurrent connection limits."""
+    with aioresponses() as mocked:
+        url = "http://test.api/test"
+        mocked.get(
+            url,
+            status=200,
+            payload={"result": "success"},
+            repeat=True
+        )
+
+        async def make_request():
+            return await api_client.request("GET", "test")
+
+        # Make concurrent requests
+        results = await asyncio.gather(*[
+            make_request() for _ in range(5)
+        ])
+
+        assert len(results) == 5
+        assert all(r == {"result": "success"} for r in results)

tests/test_cache.py

@@ -0,0 +1,197 @@
+"""Tests for the caching module."""
+
+import time
+from datetime import datetime, timedelta
+from typing import Optional
+from unittest.mock import MagicMock, patch
+
+import pytest
+import redis
+from redis.exceptions import RedisError
+
+from tools.cache import CacheConfig, CacheEntry, CacheManager, LRUCache, cached
+from tools.stats import UsageStats
+
+@pytest.fixture
+def cache_config() -> CacheConfig:
+    """Create a test cache configuration."""
+    return CacheConfig(
+        redis_host="localhost",
+        redis_port=6379,
+        redis_db=0,
+        default_ttl=60,
+        local_cache_size=10,
+        enable_local_cache=True,
+        enable_redis_cache=True
+    )
+
+@pytest.fixture
+def mock_redis() -> MagicMock:
+    """Create a mock Redis client."""
+    with patch("redis.Redis") as mock:
+        mock.return_value.ping.return_value = True
+        yield mock.return_value
+
+@pytest.fixture
+def mock_stats() -> MagicMock:
+    """Create a mock stats manager."""
+    return MagicMock(spec=UsageStats)
+
+@pytest.fixture
+def cache_manager(
+    cache_config: CacheConfig,
+    mock_redis: MagicMock,
+    mock_stats: MagicMock
+) -> CacheManager:
+    """Create a test cache manager."""
+    with patch("redis.Redis", return_value=mock_redis):
+        return CacheManager(cache_config, mock_stats)
+
+def test_lru_cache_basic_operations():
+    """Test basic LRU cache operations."""
+    cache: LRUCache[str, int] = LRUCache(max_size=2)
+
+    # Test set and get
+    cache.set("a", 1)
+    cache.set("b", 2)
+    assert cache.get("a") == 1
+    assert cache.get("b") == 2
+
+    # Test LRU eviction
+    cache.set("c", 3)  # Should evict "a"
+    assert cache.get("a") is None
+    assert cache.get("b") == 2
+    assert cache.get("c") == 3
+
+    # Test removal
+    cache.remove("b")
+    assert cache.get("b") is None
+
+    # Test clear
+    cache.clear()
+    assert cache.get("c") is None
+
+def test_lru_cache_ttl():
+    """Test LRU cache TTL functionality."""
+    cache: LRUCache[str, int] = LRUCache(max_size=2)
+
+    # Set with TTL
+    cache.set("a", 1, ttl=1)
+    assert cache.get("a") == 1
+
+    # Wait for expiration
+    time.sleep(1.1)
+    assert cache.get("a") is None
+
+def test_cache_entry_serialization():
+    """Test cache entry serialization."""
+    entry = CacheEntry[str](
+        value="test",
+        created_at=datetime.utcnow(),
+        expires_at=datetime.utcnow() + timedelta(seconds=60),
+        hit_count=5
+    )
+
+    # Test serialization
+    json_str = entry.to_json()
+
+    # Test deserialization
+    loaded_entry = CacheEntry.from_json(json_str, str)
+    assert loaded_entry.value == entry.value
+    assert loaded_entry.hit_count == entry.hit_count
+    assert abs((loaded_entry.created_at - entry.created_at).total_seconds()) < 1
+    assert abs((loaded_entry.expires_at - entry.expires_at).total_seconds()) < 1
+
+def test_cache_manager_local_only(cache_config: CacheConfig, mock_stats: MagicMock):
+    """Test cache manager with local cache only."""
+    config = cache_config.copy()
+    config.enable_redis_cache = False
+    manager = CacheManager(config, mock_stats)
+
+    # Test set and get
+    manager.set("key", "value")
+    assert manager.get("key", str) == "value"
+
+    # Test stats recording
+    mock_stats.record_cache_operation.assert_called()
+
+def test_cache_manager_redis_operations(
+    cache_manager: CacheManager,
+    mock_redis: MagicMock
+):
+    """Test cache manager Redis operations."""
+    # Setup mock Redis response
+    entry = CacheEntry[str](value="test", expires_at=datetime.utcnow() + timedelta(seconds=60))
+    mock_redis.get.return_value = entry.to_json()
+
+    # Test get from Redis
+    value = cache_manager.get("key", str)
+    assert value == "test"
+    mock_redis.get.assert_called_with("key")
+
+    # Test set to Redis
+    cache_manager.set("key", "value", ttl=60)
+    mock_redis.setex.assert_called()
+
+    # Test Redis error handling
+    mock_redis.get.side_effect = RedisError("Test error")
+    assert cache_manager.get("key", str) is None
+
+def test_cache_manager_two_level_caching(
+    cache_manager: CacheManager,
+    mock_redis: MagicMock
+):
+    """Test two-level caching strategy."""
+    # Set value
+    cache_manager.set("key", "value")
+
+    # First get should use Redis
+    entry = CacheEntry[str](value="value", expires_at=datetime.utcnow() + timedelta(seconds=60))
+    mock_redis.get.return_value = entry.to_json()
+    assert cache_manager.get("key", str) == "value"
+    mock_redis.get.assert_called_once()
+
+    # Second get should use local cache
+    mock_redis.get.reset_mock()
+    assert cache_manager.get("key", str) == "value"
+    mock_redis.get.assert_not_called()
+
+@pytest.mark.parametrize("ttl", [None, 60])
+def test_cached_decorator(cache_manager: CacheManager, ttl: Optional[int]):
+    """Test cached decorator."""
+    call_count = 0
+
+    @cached(ttl=ttl, cache_manager=cache_manager)
+    def test_func(x: int, y: str = "default") -> str:
+        nonlocal call_count
+        call_count += 1
+        return f"{x}-{y}"
+
+    # First call should execute function
+    result1 = test_func(1, y="test")
+    assert result1 == "1-test"
+    assert call_count == 1
+
+    # Second call should use cache
+    result2 = test_func(1, y="test")
+    assert result2 == "1-test"
+    assert call_count == 1
+
+    # Different arguments should execute function
+    result3 = test_func(2, y="test")
+    assert result3 == "2-test"
+    assert call_count == 2
+
+def test_cached_decorator_type_handling(cache_manager: CacheManager):
+    """Test cached decorator type handling."""
+    @cached(cache_manager=cache_manager)
+    def test_func() -> Optional[str]:
+        return "test"
+
+    # Should correctly handle Optional types
+    result = test_func()
+    assert result == "test"
+
+    # Should correctly cache and return the value
+    cached_result = test_func()
+    assert cached_result == "test"

tests/test_cache_invalidation.py

@@ -0,0 +1,221 @@
+"""Tests for cache invalidation strategies."""
+
+from datetime import datetime, timedelta, timezone
+from typing import List, Pattern
+from unittest.mock import MagicMock, call
+
+import pytest
+from typing_extensions import TypeAlias
+
+from tools.cache import CacheConfig, CacheManager
+from tools.cache_invalidation import (
+    CacheInvalidator,
+    InvalidationEvent,
+    InvalidationStrategy,
+)
+
+# Type aliases
+PatternType: TypeAlias = "str | Pattern[str]"
+
+@pytest.fixture
+def cache_config() -> CacheConfig:
+    """Create a test cache configuration."""
+    return CacheConfig(
+        redis_host="localhost",
+        redis_port=6379,
+        redis_db=0,
+        default_ttl=60,
+        local_cache_size=10,
+        enable_local_cache=True,
+        enable_redis_cache=True
+    )
+
+@pytest.fixture
+def mock_cache_manager(cache_config: CacheConfig) -> MagicMock:
+    """Create a mock cache manager."""
+    manager = MagicMock(spec=CacheManager)
+    manager.config = cache_config
+    return manager
+
+@pytest.fixture
+def invalidator(mock_cache_manager: MagicMock) -> CacheInvalidator:
+    """Create a test cache invalidator."""
+    return CacheInvalidator(mock_cache_manager)
+
+def test_add_and_remove_tags(invalidator: CacheInvalidator):
+    """Test adding and removing tags from cache keys."""
+    # Add tags
+    invalidator.add_tags("key1", ["tag1", "tag2"])
+    invalidator.add_tags("key2", ["tag2", "tag3"])
+
+    # Verify tag mappings
+    assert invalidator.key_tags["key1"] == {"tag1", "tag2"}
+    assert invalidator.key_tags["key2"] == {"tag2", "tag3"}
+    assert invalidator.tag_keys["tag1"] == {"key1"}
+    assert invalidator.tag_keys["tag2"] == {"key1", "key2"}
+    assert invalidator.tag_keys["tag3"] == {"key2"}
+
+    # Remove specific tags
+    invalidator.remove_tags("key1", ["tag1"])
+    assert invalidator.key_tags["key1"] == {"tag2"}
+    assert "tag1" not in invalidator.tag_keys
+
+    # Remove all tags
+    invalidator.remove_tags("key2")
+    assert "key2" not in invalidator.key_tags
+    assert invalidator.tag_keys["tag2"] == {"key1"}
+    assert "tag3" not in invalidator.tag_keys
+
+def test_invalidate_by_pattern(
+    invalidator: CacheInvalidator,
+    mock_cache_manager: MagicMock
+):
+    """Test pattern-based cache invalidation."""
+    # Setup test data
+    invalidator.add_tags("user:1", ["user"])
+    invalidator.add_tags("user:2", ["user"])
+    invalidator.add_tags("post:1", ["post"])
+
+    # Test glob pattern invalidation
+    keys = invalidator.invalidate_by_pattern("user:*")
+    assert set(keys) == {"user:1", "user:2"}
+    assert mock_cache_manager.remove.call_count == 2
+    mock_cache_manager.remove.assert_has_calls([
+        call("user:1"),
+        call("user:2")
+    ], any_order=True)
+
+    # Verify tags were removed
+    assert "user:1" not in invalidator.key_tags
+    assert "user:2" not in invalidator.key_tags
+    assert "post:1" in invalidator.key_tags
+
+def test_invalidate_by_tags(
+    invalidator: CacheInvalidator,
+    mock_cache_manager: MagicMock
+):
+    """Test tag-based cache invalidation."""
+    # Setup test data
+    invalidator.add_tags("key1", ["tag1", "tag2"])
+    invalidator.add_tags("key2", ["tag2", "tag3"])
+    invalidator.add_tags("key3", ["tag3"])
+
+    # Test invalidation with any tag
+    keys = invalidator.invalidate_by_tags(["tag1", "tag3"])
+    assert set(keys) == {"key1", "key2", "key3"}
+    assert mock_cache_manager.remove.call_count == 3
+
+    # Test invalidation with all tags
+    invalidator.add_tags("key4", ["tag4", "tag5"])
+    invalidator.add_tags("key5", ["tag4", "tag5", "tag6"])
+    keys = invalidator.invalidate_by_tags(["tag4", "tag5"], match_all=True)
+    assert set(keys) == {"key4", "key5"}
+
+def test_invalidate_by_time(
+    invalidator: CacheInvalidator,
+    mock_cache_manager: MagicMock
+):
+    """Test time-based cache invalidation."""
+    now = datetime.now(timezone.utc)
+    old_time = now - timedelta(hours=2)
+    recent_time = now - timedelta(minutes=30)
+
+    # Setup test data with different timestamps
+    invalidator.add_tags("old_key", ["tag1"])
+    invalidator.key_timestamps["old_key"] = old_time
+
+    invalidator.add_tags("recent_key", ["tag1"])
+    invalidator.key_timestamps["recent_key"] = recent_time
+
+    # Test invalidation of old keys
+    keys = invalidator.invalidate_by_time(timedelta(hours=1))
+    assert keys == ["old_key"]
+    mock_cache_manager.remove.assert_called_once_with("old_key")
+
+    # Verify old key was removed from all mappings
+    assert "old_key" not in invalidator.key_tags
+    assert "old_key" not in invalidator.key_timestamps
+    assert "recent_key" in invalidator.key_tags
+
+def test_bulk_invalidation(
+    invalidator: CacheInvalidator,
+    mock_cache_manager: MagicMock
+):
+    """Test bulk cache invalidation."""
+    now = datetime.now(timezone.utc)
+    old_time = now - timedelta(hours=2)
+
+    # Setup test data
+    invalidator.add_tags("user:1", ["user", "active"])
+    invalidator.add_tags("user:2", ["user", "inactive"])
+    invalidator.add_tags("post:1", ["post"])
+    invalidator.key_timestamps["user:2"] = old_time
+
+    # Test bulk invalidation with multiple criteria
+    keys = invalidator.bulk_invalidate(
+        patterns=["user:*"],
+        tags=["inactive"],
+        max_age=timedelta(hours=1)
+    )
+    assert set(keys) == {"user:1", "user:2"}
+    assert mock_cache_manager.remove.call_count == 2
+
+def test_invalidation_callbacks(invalidator: CacheInvalidator):
+    """Test invalidation callbacks."""
+    callback_called = False
+
+    def test_callback() -> None:
+        nonlocal callback_called
+        callback_called = True
+
+    # Register callback
+    invalidator.register_callback("test", test_callback)
+
+    # Setup test data
+    invalidator.add_tags("key1", ["tag1"])
+
+    # Test callback execution
+    invalidator.invalidate_by_pattern("key*", callback="test")
+    assert callback_called
+
+def test_invalidation_events(
+    invalidator: CacheInvalidator,
+    mock_cache_manager: MagicMock
+):
+    """Test invalidation events."""
+    # Setup test data
+    invalidator.add_tags("user:1", ["user"])
+    invalidator.add_tags("post:1", ["post"])
+
+    # Test pattern invalidation event
+    event = InvalidationEvent(
+        strategy=InvalidationStrategy.PATTERN,
+        pattern="user:*"
+    )
+    keys = invalidator.record_invalidation(event)
+    assert keys == ["user:1"]
+
+    # Test tag invalidation event
+    event = InvalidationEvent(
+        strategy=InvalidationStrategy.TAG,
+        tags=["post"]
+    )
+    keys = invalidator.record_invalidation(event)
+    assert keys == ["post:1"]
+
+    # Test time invalidation event
+    event = InvalidationEvent(
+        strategy=InvalidationStrategy.TIME,
+        max_age=timedelta(hours=1)
+    )
+    keys = invalidator.record_invalidation(event)
+    assert keys == []
+
+    # Test bulk invalidation event
+    event = InvalidationEvent(
+        strategy=InvalidationStrategy.BULK,
+        pattern="*:1",
+        tags=["user", "post"]
+    )
+    keys = invalidator.record_invalidation(event)
+    assert set(keys) == {"user:1", "post:1"}

tests/test_error_recovery.py

@@ -0,0 +1,212 @@
+"""
+Tests for the error recovery mechanisms.
+"""
+
+from datetime import datetime, timedelta
+import time
+from typing import Dict, Any, Optional, List
+import pytest
+from unittest.mock import Mock, patch
+
+from tools.error_recovery import (
+    CircuitBreaker,
+    CircuitBreakerState,
+    RetryConfig,
+    with_retry
+)
+from tools.exceptions import APIError, APIRateLimitError, APITimeoutError
+
+def test_circuit_breaker_state() -> None:
+    """Test circuit breaker state initialization and updates."""
+    state = CircuitBreakerState()
+    assert not state.is_open
+    assert state.failure_count == 0
+    assert state.last_failure_time is None
+    assert state.last_attempt_time is None
+    assert len(state.endpoints) == 0
+
+def test_retry_config() -> None:
+    """Test retry configuration initialization."""
+    config = RetryConfig()
+    assert config.max_retries == 3
+    assert config.initial_delay == 1.0
+    assert config.max_delay == 60.0
+    assert config.exponential_base == 2.0
+    assert 0 < config.jitter <= 1.0
+    assert APITimeoutError in config.retry_on
+    assert APIRateLimitError in config.retry_on
+
+def test_circuit_breaker_basic() -> None:
+    """Test basic circuit breaker functionality."""
+    cb = CircuitBreaker(failure_threshold=2)
+    
+    # Initially should allow execution
+    assert cb.can_execute("test_key")
+    
+    # Record a failure
+    cb.record_failure("test_key", "test_endpoint")
+    assert cb.can_execute("test_key")
+    
+    # Record another failure to trigger circuit open
+    cb.record_failure("test_key", "test_endpoint")
+    assert not cb.can_execute("test_key")
+    
+    # Record success should reset the circuit
+    cb.record_success("test_key")
+    assert cb.can_execute("test_key")
+    state = cb.get_state("test_key")
+    assert not state.is_open
+    assert state.failure_count == 0
+    assert len(state.endpoints) == 0
+
+def test_circuit_breaker_timeout() -> None:
+    """Test circuit breaker timeout and half-open state."""
+    cb = CircuitBreaker(
+        failure_threshold=1,
+        reset_timeout=0.1,  # Short timeout for testing
+        half_open_timeout=0.05
+    )
+    
+    # Open the circuit
+    cb.record_failure("test_key")
+    assert not cb.can_execute("test_key")
+    
+    # Wait for reset timeout
+    time.sleep(0.15)
+    
+    # Should allow one test request
+    assert cb.can_execute("test_key")
+    
+    # Should not allow another request too soon
+    assert not cb.can_execute("test_key")
+    
+    # Wait for half-open timeout
+    time.sleep(0.1)
+    
+    # Should allow another test request
+    assert cb.can_execute("test_key")
+
+@pytest.mark.parametrize("error_class", [
+    APITimeoutError,
+    APIRateLimitError,
+    TimeoutError,
+    ConnectionError
+])
+def test_retry_on_different_errors(error_class: type) -> None:
+    """Test retry behavior with different error types."""
+    retry_count = 0
+    
+    @with_retry(retry_config=RetryConfig(max_retries=2, initial_delay=0.01))
+    def failing_function() -> None:
+        nonlocal retry_count
+        retry_count += 1
+        if error_class == APIRateLimitError:
+            response = Mock()
+            response.headers = {"Retry-After": "1"}
+            error = Exception("Rate limit")
+            error.response = response
+            error.response.status_code = 429
+            raise error
+        raise error_class("Test error")
+    
+    with pytest.raises((APIError, error_class)):
+        failing_function()
+    
+    assert retry_count == 3  # Initial attempt + 2 retries
+
+def test_retry_with_success() -> None:
+    """Test successful retry after failures."""
+    attempts = 0
+    
+    @with_retry(retry_config=RetryConfig(max_retries=3, initial_delay=0.01))
+    def eventually_succeeds() -> str:
+        nonlocal attempts
+        attempts += 1
+        if attempts < 2:
+            raise APITimeoutError("test", 1.0)
+        return "success"
+    
+    result = eventually_succeeds()
+    assert result == "success"
+    assert attempts == 2
+
+def test_retry_respects_rate_limit() -> None:
+    """Test that retry mechanism respects rate limit retry-after."""
+    attempts = 0
+    start_time = time.time()
+    
+    @with_retry(retry_config=RetryConfig(max_retries=1, initial_delay=0.01))
+    def rate_limited() -> None:
+        nonlocal attempts
+        attempts += 1
+        response = Mock()
+        response.headers = {"Retry-After": "0.1"}  # 100ms
+        error = Exception("Rate limit")
+        error.response = response
+        error.response.status_code = 429
+        raise error
+    
+    with pytest.raises(APIError):
+        rate_limited()
+    
+    duration = time.time() - start_time
+    assert duration >= 0.1  # Should have waited for retry-after
+    assert attempts == 2  # Initial attempt + 1 retry
+
+def test_combined_circuit_breaker_and_retry() -> None:
+    """Test circuit breaker and retry working together."""
+    cb = CircuitBreaker(failure_threshold=3)
+    attempts = 0
+    
+    @with_retry(
+        retry_config=RetryConfig(max_retries=2, initial_delay=0.01),
+        circuit_breaker=cb
+    )
+    def failing_function() -> None:
+        nonlocal attempts
+        attempts += 1
+        raise APITimeoutError("test", 1.0)
+    
+    # First call should retry twice
+    with pytest.raises(APITimeoutError):
+        failing_function()
+    assert attempts == 3
+    
+    # Second call should retry twice
+    attempts = 0
+    with pytest.raises(APITimeoutError):
+        failing_function()
+    assert attempts == 3
+    
+    # Third call should fail immediately due to circuit breaker
+    attempts = 0
+    with pytest.raises(APIError) as exc_info:
+        failing_function()
+    assert attempts == 0
+    assert "Circuit breaker is open" in str(exc_info.value)
+
+def test_exponential_backoff() -> None:
+    """Test exponential backoff with jitter."""
+    sleep_times: List[float] = []
+    
+    @with_retry(
+        retry_config=RetryConfig(
+            max_retries=2,
+            initial_delay=0.1,
+            exponential_base=2.0,
+            jitter=0.1
+        )
+    )
+    def failing_function() -> None:
+        raise APITimeoutError("test", 1.0)
+    
+    with patch('time.sleep') as mock_sleep:
+        mock_sleep.side_effect = lambda x: sleep_times.append(x)
+        with pytest.raises(APITimeoutError):
+            failing_function()
+    
+    assert len(sleep_times) == 2
+    # First delay should be around 0.1s (with jitter)
+    assert 0.09 <= sleep_times[0] <= 0.11
+    # Second delay should be around 0.2s (with jitter)
+    assert 0.18 <= sleep_times[1] <= 0.22 

tests/test_errors.py

@@ -0,0 +1,204 @@
+"""Tests for security error handling."""
+
+import pytest
+from datetime import datetime, timedelta, timezone
+
+from tools.errors import (
+    SecurityError,
+    AuthenticationError,
+    AuthorizationError,
+    InvalidKeyError,
+    KeyExpiredError,
+    RateLimitError,
+    EncryptionError,
+    ValidationError,
+    ConfigurationError,
+)
+from tools.security import KeyManager
+
+
+def test_security_error_base():
+    """Test base security error."""
+    error = SecurityError("Test error")
+    assert str(error) == "[SECURITY_ERROR] Test error"
+    assert error.message == "Test error"
+    assert error.code == "SECURITY_ERROR"
+
+
+def test_authentication_error():
+    """Test authentication error."""
+    error = AuthenticationError("Invalid credentials")
+    assert str(error) == "[AUTH_ERROR] Invalid credentials"
+    assert error.message == "Invalid credentials"
+    assert error.code == "AUTH_ERROR"
+
+
+def test_authorization_error():
+    """Test authorization error."""
+    error = AuthorizationError("Insufficient permissions")
+    assert str(error) == "[ACCESS_DENIED] Insufficient permissions"
+    assert error.message == "Insufficient permissions"
+    assert error.code == "ACCESS_DENIED"
+
+
+def test_invalid_key_error():
+    """Test invalid key error."""
+    error = InvalidKeyError("Key not found")
+    assert str(error) == "[INVALID_KEY] Key not found"
+    assert error.message == "Key not found"
+    assert error.code == "INVALID_KEY"
+
+
+def test_key_expired_error():
+    """Test key expired error."""
+    error = KeyExpiredError("Key has expired")
+    assert str(error) == "[KEY_EXPIRED] Key has expired"
+    assert error.message == "Key has expired"
+    assert error.code == "KEY_EXPIRED"
+
+
+def test_rate_limit_error():
+    """Test rate limit error."""
+    error = RateLimitError("Too many requests", wait_time=1.5)
+    assert str(error) == "[RATE_LIMITED] Too many requests"
+    assert error.message == "Too many requests"
+    assert error.code == "RATE_LIMITED"
+    assert error.wait_time == 1.5
+
+
+def test_encryption_error():
+    """Test encryption error."""
+    error = EncryptionError("Failed to decrypt")
+    assert str(error) == "[ENCRYPTION_ERROR] Failed to decrypt"
+    assert error.message == "Failed to decrypt"
+    assert error.code == "ENCRYPTION_ERROR"
+
+
+def test_validation_error():
+    """Test validation error."""
+    # Without field
+    error = ValidationError("Invalid value")
+    assert str(error) == "[VALIDATION_ERROR] Invalid value"
+    assert error.message == "Invalid value"
+    assert error.code == "VALIDATION_ERROR"
+    assert error.field is None
+
+    # With field
+    error = ValidationError("Invalid format", field="api_key")
+    assert str(error) == "[VALIDATION_ERROR] api_key: Invalid format"
+    assert error.message == "api_key: Invalid format"
+    assert error.code == "VALIDATION_ERROR"
+    assert error.field == "api_key"
+
+
+def test_configuration_error():
+    """Test configuration error."""
+    error = ConfigurationError("Invalid settings")
+    assert str(error) == "[CONFIG_ERROR] Invalid settings"
+    assert error.message == "Invalid settings"
+    assert error.code == "CONFIG_ERROR"
+
+
+@pytest.fixture
+def key_manager():
+    """Create test key manager."""
+    return KeyManager(keys_file="test_keys.json")
+
+
+def test_invalid_key_handling(key_manager):
+    """Test handling of invalid keys."""
+    # Test adding invalid key
+    with pytest.raises(ValidationError) as exc:
+        key_manager.add_key("test", "invalid@key")
+    assert "API key must contain only" in str(exc.value)
+    assert exc.value.field == "key"
+
+    # Test getting non-existent key
+    with pytest.raises(InvalidKeyError) as exc:
+        key_manager.get_key("nonexistent")
+    assert "Key 'nonexistent' not found" in str(exc.value)
+
+    # Test removing non-existent key
+    with pytest.raises(InvalidKeyError) as exc:
+        key_manager.remove_key("nonexistent")
+    assert "Key 'nonexistent' not found" in str(exc.value)
+
+
+def test_expired_key_handling(key_manager):
+    """Test handling of expired keys."""
+    # Add key that expires in 1 second
+    expires_at = datetime.now(timezone.utc) + timedelta(seconds=1)
+    key_manager.add_key("test", "valid-key-123", expires_at=expires_at)
+
+    # Key should be valid initially
+    key = key_manager.get_key("test")
+    assert key is not None
+    assert key.is_valid
+
+    # Wait for key to expire
+    import time
+    time.sleep(1.1)
+
+    # Key should raise expired error
+    with pytest.raises(KeyExpiredError) as exc:
+        key_manager.get_key("test")
+    assert "Key 'test' has expired" in str(exc.value)
+
+
+@pytest.mark.asyncio
+async def test_rate_limit_handling(key_manager):
+    """Test handling of rate limits."""
+    # Add key with low rate limit
+    key_manager.add_key(
+        "test",
+        "valid-key-123",
+        rate_limit=1.0,  # 1 request per second
+        burst_limit=1
+    )
+
+    # First request should succeed
+    wait_time = await key_manager.check_rate_limit("test")
+    assert wait_time == 0
+
+    # Second request should be rate limited
+    with pytest.raises(RateLimitError) as exc:
+        await key_manager.check_rate_limit("test")
+    assert "Rate limit exceeded" in str(exc.value)
+    assert exc.value.wait_time > 0
+
+
+def test_encryption_handling(key_manager):
+    """Test handling of encryption errors."""
+    # Test invalid encryption key
+    with pytest.raises(EncryptionError) as exc:
+        KeyManager(encryption_key="invalid-key")
+    assert "Invalid base64 encoding" in str(exc.value)
+
+    # Test corrupted keys file
+    with open("test_keys.json", "wb") as f:
+        f.write(b"corrupted data")
+
+    with pytest.raises(EncryptionError) as exc:
+        key_manager._load_keys()
+    assert "Failed to decrypt keys file" in str(exc.value)
+
+
+def test_configuration_handling(key_manager):
+    """Test handling of configuration errors."""
+    # Test invalid environment variable
+    import os
+    os.environ["API_TEST_KEY"] = "invalid@key"
+    os.environ["API_TEST_RATE_LIMIT"] = "invalid"
+
+    with pytest.raises(ConfigurationError) as exc:
+        key_manager.get_key("test")
+    assert "Invalid environment configuration" in str(exc.value)
+
+    # Test invalid rate limits
+    with pytest.raises(ValidationError) as exc:
+        key_manager.add_key("test", "valid-key-123", rate_limit=0)
+    assert "Rate limit must be between" in str(exc.value)
+
+    with pytest.raises(ValidationError) as exc:
+        key_manager.add_key("test", "valid-key-123", burst_limit=0)
+    assert "Burst limit must be at least" in str(exc.value)

tests/test_gradio_ui.py

@@ -0,0 +1,92 @@
+"""Tests for the Gradio UI implementation."""
+
+from typing import List, Optional, Generator, Any, Dict
+import os
+import tempfile
+try:
+    import gradio as gr
+except ImportError:
+    print("Warning: gradio package not found. Please install it with 'pip install gradio'")
+from Gradio_UI import GradioUI
+
+class MockTool:
+    """Mock tool for testing."""
+    def __init__(self) -> None:
+        self.description: str = "A mock tool for testing"
+        self.name: str = "mock_tool"
+        self.inputs: Dict[str, Dict[str, str]] = {
+            "input_text": {
+                "type": "string",
+                "description": "Input text to process"
+            }
+        }
+        self.output_type: str = "string"
+
+    def run(self, input_text: str) -> str:
+        """Process input text."""
+        return f"Processed: {input_text}"
+
+class MockModel:
+    """Mock model for testing."""
+    def generate(self, prompt: str) -> str:
+        """Generate a response to the prompt."""
+        return f"Response to: {prompt}"
+
+class MockAgent:
+    """Mock agent for testing."""
+    def __init__(self) -> None:
+        self.tools: List[MockTool] = [MockTool()]
+        self.model: MockModel = MockModel()
+
+    def run(
+        self,
+        task: str,
+        stream: bool = False,
+        reset: bool = False,
+        additional_args: Optional[Dict[str, Any]] = None
+    ) -> List[str]:
+        """Run the agent with the given task."""
+        return [self.model.generate(task)]
+
+def test_gradio_ui_initialization() -> None:
+    """Test GradioUI initialization."""
+    agent = MockAgent()
+    ui = GradioUI(agent)
+    assert ui.agent == agent
+
+def test_gradio_ui_interaction() -> None:
+    """Test GradioUI interaction."""
+    agent = MockAgent()
+    ui = GradioUI(agent)
+    messages: List[Dict[str, Any]] = []
+    response_generator: Generator[List[Dict[str, Any]], None, None] = ui.interact_with_agent("Hello", messages)
+    responses: List[List[Dict[str, Any]]] = list(response_generator)
+    assert len(responses) > 0
+    assert any("Hello" in str(msg) for msg in responses[0])
+
+def test_gradio_ui_file_upload() -> None:
+    """Test GradioUI file upload."""
+    # Create a temporary directory for file uploads
+    with tempfile.TemporaryDirectory() as temp_dir:
+        agent = MockAgent()
+        ui = GradioUI(agent, file_upload_folder=temp_dir)
+
+        # Create a test file
+        test_file_path = os.path.join(temp_dir, "test.txt")
+        with open(test_file_path, "w") as f:
+            f.write("Test content")
+
+        # Create a mock file object
+        class MockFile:
+            def __init__(self, path: str) -> None:
+                self.name: str = path
+
+        mock_file = MockFile(test_file_path)
+        file_uploads_log: List[str] = []
+
+        # Test file upload
+        result, log = ui.upload_file(mock_file, file_uploads_log)
+        assert isinstance(result, gr.Textbox)
+        assert "File uploaded:" in result.value
+        assert len(log) == 1  # One file should be added to the log
+        assert os.path.splitext(os.path.basename(test_file_path))[0] in os.path.basename(log[0])  # The file name (without extension) should be in the log

tests/test_health.py

@@ -0,0 +1,136 @@
+"""
+Tests for the health check functionality.
+"""
+
+import pytest
+from datetime import datetime, timedelta
+from unittest.mock import Mock, patch
+
+from tools.health import HealthCheck, HealthStatus
+from tools.error_recovery import CircuitBreaker, CircuitBreakerState
+
+@pytest.fixture
+def health_check() -> HealthCheck:
+    """Create a health check instance for testing."""
+    return HealthCheck(
+        circuit_breaker=CircuitBreaker(),
+        memory_threshold=90.0,
+        cpu_threshold=80.0
+    )
+
+def test_health_status_init() -> None:
+    """Test health status initialization."""
+    status = HealthStatus()
+    assert status.status == "healthy"
+    assert isinstance(status.timestamp, datetime)
+    assert status.checks == {}
+    assert status.details == {}
+
+@patch("psutil.virtual_memory")
+@patch("psutil.cpu_percent")
+def test_check_system_resources(mock_cpu: Mock, mock_memory: Mock, health_check: HealthCheck) -> None:
+    """Test system resource check."""
+    # Mock healthy system
+    mock_memory.return_value.percent = 50.0
+    mock_cpu.return_value = 30.0
+    
+    result = health_check.check_system_resources()
+    assert result["status"] == "healthy"
+    assert result["details"]["memory_usage"] == 50.0
+    assert result["details"]["cpu_usage"] == 30.0
+    
+    # Mock degraded system
+    mock_memory.return_value.percent = 95.0
+    mock_cpu.return_value = 85.0
+    
+    result = health_check.check_system_resources()
+    assert result["status"] == "degraded"
+    assert result["details"]["memory_usage"] == 95.0
+    assert result["details"]["cpu_usage"] == 85.0
+
+def test_check_circuit_breaker(health_check: HealthCheck) -> None:
+    """Test circuit breaker status check."""
+    # Test with no open circuits
+    result = health_check.check_circuit_breaker()
+    assert result["status"] == "healthy"
+    assert result["details"]["total_circuits"] == 0
+    assert result["details"]["open_circuits"] == []
+    
+    # Test with open circuit
+    state = CircuitBreakerState(
+        is_open=True,
+        failure_count=5,
+        last_failure_time=datetime.utcnow(),
+        endpoints={"api/weather"}
+    )
+    health_check.circuit_breaker._states["test_circuit"] = state
+    
+    result = health_check.check_circuit_breaker()
+    assert result["status"] == "degraded"
+    assert result["details"]["total_circuits"] == 1
+    assert len(result["details"]["open_circuits"]) == 1
+    assert result["details"]["open_circuits"][0]["key"] == "test_circuit"
+    assert result["details"]["open_circuits"][0]["failures"] == 5
+    assert "api/weather" in result["details"]["open_circuits"][0]["endpoints"]
+
+@patch("tools.health.requests")
+@patch("tools.health.pydantic")
+@patch("tools.health.typing_extensions")
+def test_check_dependencies(
+    mock_typing: Mock,
+    mock_pydantic: Mock,
+    mock_requests: Mock,
+    health_check: HealthCheck
+) -> None:
+    """Test dependency check."""
+    # Mock healthy dependencies
+    mock_requests.__version__ = "2.31.0"
+    mock_pydantic.__version__ = "2.5.2"
+    mock_typing.__version__ = "4.8.0"
+    
+    result = health_check.check_dependencies()
+    assert result["status"] == "healthy"
+    assert result["details"]["dependencies"]["requests"] == "2.31.0"
+    assert result["details"]["dependencies"]["pydantic"] == "2.5.2"
+    assert result["details"]["dependencies"]["typing_extensions"] == "4.8.0"
+    
+    # Test with missing dependency
+    mock_requests.__version__ = None
+    result = health_check.check_dependencies()
+    assert result["status"] == "unhealthy"
+    assert "error" in result["details"]
+
+def test_get_uptime(health_check: HealthCheck) -> None:
+    """Test uptime information."""
+    # Set start time to 1 hour ago
+    health_check.start_time = datetime.utcnow() - timedelta(hours=1)
+    
+    result = health_check.get_uptime()
+    assert result["status"] == "healthy"
+    assert "start_time" in result["details"]
+    assert result["details"]["uptime_seconds"] >= 3600
+    assert "uptime_human" in result["details"]
+
+def test_check_health(health_check: HealthCheck) -> None:
+    """Test comprehensive health check."""
+    with patch.multiple(
+        health_check,
+        check_system_resources=Mock(return_value={"status": "healthy", "details": {}}),
+        check_circuit_breaker=Mock(return_value={"status": "healthy", "details": {}}),
+        check_dependencies=Mock(return_value={"status": "healthy", "details": {}}),
+        get_uptime=Mock(return_value={"status": "healthy", "details": {}})
+    ):
+        status = health_check.check_health()
+        assert status.status == "healthy"
+        assert len(status.checks) == 4
+        assert all(check["status"] == "healthy" for check in status.checks.values())
+        
+        # Test degraded status
+        health_check.check_system_resources.return_value = {"status": "degraded", "details": {}}
+        status = health_check.check_health()
+        assert status.status == "degraded"
+        
+        # Test unhealthy status
+        health_check.check_dependencies.return_value = {"status": "unhealthy", "details": {}}
+        status = health_check.check_health()
+        assert status.status == "unhealthy" 

tests/test_logging.py

@@ -0,0 +1,126 @@
+"""
+Tests for the logging configuration.
+"""
+
+import os
+import logging
+import pytest
+from pathlib import Path
+from unittest.mock import patch, Mock
+from datetime import datetime
+
+from tools.logging_config import setup_logging, get_log_stats
+
+@pytest.fixture
+def temp_log_dir(tmp_path):
+    """Create a temporary log directory."""
+    log_dir = tmp_path / "logs"
+    log_dir.mkdir()
+    return log_dir
+
+def test_setup_logging_basic(temp_log_dir):
+    """Test basic logging setup."""
+    logger = setup_logging(
+        log_dir=str(temp_log_dir),
+        log_level="INFO"
+    )
+    
+    assert isinstance(logger, logging.Logger)
+    assert logger.level == logging.INFO
+    assert len(logger.handlers) >= 1  # At least one handler
+    
+    # Check if log file was created
+    log_file = temp_log_dir / "assistant.log"
+    assert log_file.exists()
+
+def test_setup_logging_custom_format(temp_log_dir):
+    """Test logging setup with custom format."""
+    custom_format = "%(levelname)s - %(message)s"
+    custom_date = "%H:%M:%S"
+    
+    logger = setup_logging(
+        log_dir=str(temp_log_dir),
+        log_format=custom_format,
+        date_format=custom_date
+    )
+    
+    file_handler = next(h for h in logger.handlers 
+                       if isinstance(h, logging.handlers.RotatingFileHandler))
+    formatter = file_handler.formatter
+    
+    assert formatter._fmt == custom_format
+    assert formatter.datefmt == custom_date
+
+def test_setup_logging_rotation(temp_log_dir):
+    """Test log file rotation."""
+    max_bytes = 100
+    backup_count = 3
+    
+    logger = setup_logging(
+        log_dir=str(temp_log_dir),
+        max_bytes=max_bytes,
+        backup_count=backup_count
+    )
+    
+    # Write enough data to trigger rotation
+    for i in range(10):
+        logger.info("x" * 20)  # Each log entry > 20 bytes with timestamps etc.
+    
+    # Check if backup files were created
+    backup_files = list(temp_log_dir.glob("assistant.log.*"))
+    assert len(backup_files) > 0
+    assert len(backup_files) <= backup_count
+
+def test_setup_logging_environment(temp_log_dir):
+    """Test logging setup in different environments."""
+    # Test production environment
+    with patch.dict(os.environ, {"ENVIRONMENT": "production"}):
+        logger = setup_logging(log_dir=str(temp_log_dir))
+        console_handlers = [h for h in logger.handlers 
+                          if isinstance(h, logging.StreamHandler)]
+        assert len(console_handlers) == 0
+    
+    # Test development environment
+    with patch.dict(os.environ, {"ENVIRONMENT": "development"}):
+        logger = setup_logging(log_dir=str(temp_log_dir))
+        console_handlers = [h for h in logger.handlers 
+                          if isinstance(h, logging.StreamHandler)]
+        assert len(console_handlers) == 1
+
+@patch('os.statvfs')
+def test_get_log_stats(mock_statvfs, temp_log_dir):
+    """Test log statistics collection."""
+    # Create a log file and some backups
+    log_file = temp_log_dir / "assistant.log"
+    log_file.write_text("test log content")
+    
+    backup1 = temp_log_dir / "assistant.log.1"
+    backup1.write_text("backup 1 content")
+    
+    # Mock filesystem stats
+    mock_stat = Mock()
+    mock_stat.f_blocks = 1000
+    mock_stat.f_frsize = 4096
+    mock_statvfs.return_value = mock_stat
+    
+    with patch('tools.logging_config.Path') as mock_path:
+        mock_path.return_value = temp_log_dir
+        stats = get_log_stats()
+    
+    assert stats["backup_files"] == 1
+    assert stats["current_log_size"] > 0
+    assert stats["total_size"] > 0
+    assert stats["directory_usage"] >= 0
+    assert stats["last_rotation"] is not None
+
+def test_get_log_stats_no_logs(temp_log_dir):
+    """Test log statistics with no log files."""
+    with patch('tools.logging_config.Path') as mock_path:
+        mock_path.return_value = temp_log_dir
+        stats = get_log_stats()
+    
+    assert stats["backup_files"] == 0
+    assert stats["current_log_size"] == 0
+    assert stats["total_size"] == 0
+    assert stats["directory_usage"] == 0
+    assert stats["last_rotation"] is None 

tests/test_monitoring.py

@@ -0,0 +1,160 @@
+"""Tests for performance monitoring utilities."""
+
+import asyncio
+from typing import AsyncGenerator
+
+import pytest
+from pytest_asyncio import fixture
+
+from tools.monitoring import (
+    ErrorMetrics,
+    LatencyMetrics,
+    PerformanceMonitor,
+)
+
+@fixture
+async def monitor() -> AsyncGenerator[PerformanceMonitor, None]:
+    """Create a test performance monitor."""
+    monitor = PerformanceMonitor(metrics_ttl=60, max_metrics=10)
+    yield monitor
+
+@pytest.mark.asyncio
+async def test_latency_metrics():
+    """Test latency metrics tracking."""
+    metrics = LatencyMetrics()
+
+    # Test initial state
+    assert metrics.count == 0
+    assert metrics.avg_time == 0.0
+
+    # Test single measurement
+    await metrics.add_measurement(0.1)
+    assert metrics.count == 1
+    assert metrics.total_time == 0.1
+    assert metrics.min_time == 0.1
+    assert metrics.max_time == 0.1
+    assert metrics.avg_time == 0.1
+
+    # Test multiple measurements
+    await metrics.add_measurement(0.2)
+    await metrics.add_measurement(0.3)
+    assert metrics.count == 3
+    assert metrics.total_time == 0.6
+    assert metrics.min_time == 0.1
+    assert metrics.max_time == 0.3
+    assert metrics.avg_time == 0.2
+
+@pytest.mark.asyncio
+async def test_error_metrics():
+    """Test error metrics tracking."""
+    metrics = ErrorMetrics()
+
+    # Test initial state
+    assert metrics.total_errors == 0
+    assert not metrics.error_counts
+
+    # Test error recording
+    await metrics.record_error("ValueError")
+    assert metrics.total_errors == 1
+    assert metrics.error_counts["ValueError"] == 1
+
+    # Test multiple errors
+    await metrics.record_error("ValueError")
+    await metrics.record_error("TypeError")
+    assert metrics.total_errors == 3
+    assert metrics.error_counts["ValueError"] == 2
+    assert metrics.error_counts["TypeError"] == 1
+
+@pytest.mark.asyncio
+async def test_request_tracking(monitor: PerformanceMonitor):
+    """Test request tracking functionality."""
+    # Start request
+    start_time = await monitor.start_request("/test/endpoint")
+    await asyncio.sleep(0.1)  # Simulate request time
+
+    # End request successfully
+    await monitor.end_request("/test/endpoint", start_time)
+
+    metrics = await monitor.get_metrics_report()
+    assert metrics["throughput"]["total_requests"] == 1
+    assert metrics["latencies"]["/test/endpoint"]["count"] == 1
+    assert metrics["latencies"]["/test/endpoint"]["avg_ms"] >= 100  # At least 100ms
+
+    # Test error tracking
+    start_time = await monitor.start_request("/error/endpoint")
+    await monitor.end_request("/error/endpoint", start_time, error=ValueError("Test error"))
+
+    metrics = await monitor.get_metrics_report()
+    assert metrics["errors"]["total"] == 1
+    assert metrics["errors"]["by_type"]["ValueError"] == 1
+
+@pytest.mark.asyncio
+async def test_connection_tracking(monitor: PerformanceMonitor):
+    """Test connection pool metrics tracking."""
+    # Record connection states
+    await monitor.record_connection_state(1, 0.1)
+    await monitor.record_connection_state(2, 0.2)
+    await monitor.record_connection_state(1, 0.1)
+
+    metrics = await monitor.get_metrics_report()
+    assert metrics["connections"]["max_seen"] == 2
+    assert metrics["connections"]["active"] == 1
+    assert metrics["connections"]["total_wait_time"] == 0.4
+
+@pytest.mark.asyncio
+async def test_rate_limit_tracking(monitor: PerformanceMonitor):
+    """Test rate limit metrics tracking."""
+    # Record rate limit delays
+    await monitor.record_rate_limit_delay(0.1)
+    await monitor.record_rate_limit_delay(0.2)
+
+    metrics = await monitor.get_metrics_report()
+    assert metrics["rate_limiting"]["delay_count"] == 2
+    assert metrics["rate_limiting"]["total_delays"] == 0.3
+    assert metrics["rate_limiting"]["avg_delay"] == 0.15
+
+@pytest.mark.asyncio
+async def test_batch_tracking(monitor: PerformanceMonitor):
+    """Test batch processing metrics tracking."""
+    # Record batch metrics
+    await monitor.record_batch_metrics(10, 0.1)
+    await monitor.record_batch_metrics(20, 0.2)
+
+    metrics = await monitor.get_metrics_report()
+    assert metrics["batch_processing"]["total_batches"] == 2
+    assert metrics["batch_processing"]["avg_size"] == 15.0
+    assert metrics["batch_processing"]["avg_processing_time"] == 0.15
+
+@pytest.mark.asyncio
+async def test_throughput_calculation(monitor: PerformanceMonitor):
+    """Test throughput calculation."""
+    # Simulate requests over time
+    for _ in range(5):
+        await monitor.start_request("/test/endpoint")
+        await asyncio.sleep(0.1)
+
+    metrics = await monitor.get_metrics_report()
+    assert 8.0 <= metrics["throughput"]["current_rps"] <= 12.0  # Approximately 10 RPS
+
+@pytest.mark.asyncio
+async def test_metrics_ttl(monitor: PerformanceMonitor):
+    """Test metrics time-to-live functionality."""
+    # Add initial metrics
+    start_time = await monitor.start_request("/test/endpoint")
+    await monitor.end_request("/test/endpoint", start_time)
+
+    # Wait for TTL
+    await asyncio.sleep(1.1)  # Just over the 1 second TTL
+
+    metrics = await monitor.get_metrics_report()
+    assert not metrics["latencies"]  # Metrics should have expired
+
+@pytest.mark.asyncio
+async def test_max_metrics_limit(monitor: PerformanceMonitor):
+    """Test maximum metrics limit."""
+    # Add more metrics than the limit
+    for i in range(15):  # Max is 10
+        await monitor.record_batch_metrics(i, 0.1)
+
+    assert len(monitor.batch_sizes) == 10  # Should be limited to 10
+    assert monitor.batch_sizes[0] == 5  # Should have removed oldest entries