Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
215 lines (165 loc) · 5.48 KB

CONTRIBUTING.md

File metadata and controls

215 lines (165 loc) · 5.48 KB

Contributing to AI Secretary System

Thank you for your interest in contributing! This document provides guidelines for contributing to the project.

Development Setup

Prerequisites

  • Python 3.11+
  • Node.js 18+
  • Docker & Docker Compose (for containerized development)
  • NVIDIA GPU with 12GB+ VRAM (for GPU features, optional)

Local Setup

# Clone repository
git clone https://github.com/ShaerWare/AI_Secretary_System
cd AI_Secretary_System

# Create Python virtual environment
python3.11 -m venv .venv
source .venv/bin/activate

# Install development dependencies
pip install -r requirements.txt
pip install ruff mypy pre-commit pytest pytest-asyncio pytest-cov

# Install pre-commit hooks
pre-commit install

# Setup admin panel
cd admin && npm install && cd ..

# Copy environment file
cp .env.docker.example .env

Code Style

Python

  • We use ruff for linting and formatting
  • Line length: 100 characters
  • Cyrillic characters allowed in strings (Russian language support)
# Check code
ruff check .

# Auto-fix issues
ruff check . --fix

# Format code
ruff format .

TypeScript/Vue

  • We use ESLint and Prettier
cd admin
npm run lint

Pre-commit

All checks run automatically on commit:

# Run all checks manually
pre-commit run --all-files

Pull Request Process

1. Create a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description

2. Make Changes

  • Follow existing code patterns
  • Add tests for new functionality
  • Update documentation if needed

3. Test Your Changes

# Python tests
pytest tests/ -v

# Linting
ruff check .
ruff format --check .

# Frontend
cd admin && npm run lint && npm run build

4. Commit

Follow Conventional Commits:

feat: add new TTS voice preset
fix: resolve chat session memory leak
docs: update API documentation
refactor: simplify LLM provider factory
test: add unit tests for FAQ service
chore: update dependencies

5. Push and Create PR

git push origin feature/your-feature-name

Then create a Pull Request on GitHub with:

  • Clear description of changes
  • Link to related issue (if any)
  • Screenshots for UI changes

Project Structure

AI_Secretary_System/
├── orchestrator.py          # FastAPI entry point
├── app/
│   ├── routers/             # Facade re-exports (28 files, 1–3 lines each)
│   ├── dependencies.py      # Dependency injection
│   ├── rate_limiter.py      # Rate limiting
│   └── security_headers.py  # Security middleware
├── modules/                 # Domain modules
│   ├── core/                # EventBus, TaskRegistry, HealthRegistry + core services
│   ├── chat/                # ChatService, ChatShareService
│   ├── knowledge/           # FAQService, KnowledgeDocService, KnowledgeCollectionService
│   ├── channels/telegram/   # BotInstanceService, TelegramSessionService
│   ├── channels/whatsapp/   # WhatsAppInstanceService
│   ├── channels/widget/     # WidgetInstanceService
│   ├── kanban/              # KanbanService, KanbanProjectService
│   ├── llm/                 # CloudProviderService
│   ├── monitoring/          # AuditService, PaymentService
│   └── ...                  # admin, speech, crm, ecommerce, telephony, claude_code
├── db/
│   ├── models.py            # SQLAlchemy models (imports from modules/*/models.py)
│   ├── integration.py       # Backward-compatible facade (aliases + singletons)
│   └── repositories/        # Data access layer
├── admin/                   # Vue 3 admin panel
│   ├── src/views/           # Page components
│   ├── src/api/             # API clients
│   └── src/stores/          # Pinia stores
├── tests/                   # Test suite
└── docs/                    # Documentation

Adding New Features

New API Endpoint

  1. Create or edit the domain router in modules/{domain}/router.py
  2. Add a facade file in app/routers/ that re-exports the router (one-liner)
  3. Router auto-registers via app/routers/__init__.py

New Cloud LLM Provider

  1. Add entry to PROVIDER_TYPES in db/models.py
  2. If OpenAI-compatible, it works automatically
  3. For custom SDK, create provider class in cloud_llm_service.py

New Admin Panel Tab

  1. Create view in admin/src/views/
  2. Add route in admin/src/router/index.ts
  3. Add translations in admin/src/plugins/i18n.ts

Testing

Running Tests

# All tests
pytest tests/ -v

# Specific file
pytest tests/unit/test_db.py -v

# By pattern
pytest -k "test_chat" -v

# Exclude slow/integration tests
pytest -m "not slow and not integration" -v

# With coverage
pytest --cov --cov-report=html

Test Markers

  • @pytest.mark.slow - Long-running tests
  • @pytest.mark.integration - Requires external services
  • @pytest.mark.gpu - Requires CUDA GPU

Reporting Issues

When reporting bugs, please include:

  • Python version (python --version)
  • OS and version
  • Steps to reproduce
  • Expected vs actual behavior
  • Relevant logs from logs/orchestrator.log

Security

If you discover a security vulnerability, please email directly instead of creating a public issue.

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Questions? Open an issue or check CLAUDE.md for detailed documentation.