Contributing

Contributing

Development Setup

git clone https://github.com/Hesper-Labs/white-ops.git
cd white-ops
cp .env.example .env
make dev  # Start with hot reload

Code Standards

Python (server + worker)

• Formatter: ruff format
• Linter: ruff check
• Type checker: mypy --strict
• Tests: pytest

TypeScript (web)

• Strict mode enabled
• ESLint for linting
• npx tsc --noEmit for type checking

Adding a New Tool

1. Create file in worker/agent/tools/<category>/your_tool.py
2. Extend BaseTool:

from typing import Any
from agent.tools.base import BaseTool

class MyTool(BaseTool):
    name = "my_tool"
    description = "What this tool does"
    parameters = {
        "type": "object",
        "properties": {
            "action": {"type": "string", "enum": ["create", "read"]},
            "data": {"type": "string"},
        },
        "required": ["action"],
    }

    async def execute(self, **kwargs: Any) -> Any:
        action = kwargs["action"]
        if action == "create":
            return "Created"
        return "Done"

3. Tool is auto-discovered at startup. No registration needed.
4. Add tests in worker/tests/

See Tool Reference for all existing tools.

Adding a New API Endpoint

1. Create server/app/api/v1/your_module.py
2. Add router in server/app/main.py:

   app.include_router(your_module.router, prefix="/api/v1/your-module", tags=["your-module"])

3. Add Pydantic schemas in server/app/schemas/
4. Add audit logging for important actions

Adding a New Frontend Page

1. Create web/src/pages/YourPage.tsx
2. Add route in web/src/App.tsx
3. Add sidebar entry in web/src/components/layout/Layout.tsx
4. Add mock data in web/src/api/mock.ts for demo mode

PR Process

1. Fork the repo
2. Create a feature branch: git checkout -b feat/my-feature
3. Follow code standards
4. Run make lint && make test
5. Submit PR with description

Commit Messages

feat: add new Excel chart types
fix: resolve WebSocket reconnection issue
docs: update deployment guide
test: add auth endpoint tests
refactor: simplify task orchestrator