40 lines
1.9 KiB
Markdown
40 lines
1.9 KiB
Markdown
# Agent Guidelines for zynktime
|
|
|
|
## Setup
|
|
- **Install dependencies**: `pip install -r requirements.txt`
|
|
- **Set environment**: `export KLEER_API_KEY=your_key_here` (required)
|
|
- **Optional env vars**: `KLEER_USERNAME`, `KLEER_COMPANY_ID`
|
|
|
|
## Run Commands
|
|
- **Run API server**: `python main.py` (starts FastAPI on port 8000)
|
|
- **Run CLI mode**: `python main.py cli`
|
|
- **Run tests**: `pytest` or `pytest test_main.py -v`
|
|
- **Run single test**: `pytest test_main.py::TestServices::test_validate_date_valid -v`
|
|
|
|
## Project Structure
|
|
- **config.py**: Application configuration and environment variables
|
|
- **models.py**: Pydantic models for data validation
|
|
- **api_client.py**: Kleer API client with error handling
|
|
- **services.py**: Business logic (CSV parsing, time extraction, event creation)
|
|
- **main.py**: FastAPI application and endpoints
|
|
- **cli.py**: CLI interface for interactive time reporting
|
|
- **test_main.py**: Unit tests with pytest
|
|
|
|
## Code Style
|
|
|
|
**Imports**: Standard library first, third-party second, local imports last. Group by category with blank lines between groups.
|
|
|
|
**Formatting**: 4 spaces indentation, no trailing whitespace. Use type hints from `typing` (List, Dict, Any, Optional).
|
|
|
|
**Naming**: snake_case for functions/variables, PascalCase for classes, UPPER_CASE for constants. Be descriptive.
|
|
|
|
**Error Handling**: Use specific exceptions. Log with `logging.error()`. For API endpoints, raise `HTTPException` with proper status codes (404, 500, 502).
|
|
|
|
**Logging**: Use appropriate levels - INFO (normal ops), WARNING (skippable issues), ERROR (failures), DEBUG (detailed info).
|
|
|
|
**Configuration**: Use `Config` class from config.py. Never hardcode values - use Config constants or environment variables.
|
|
|
|
**API Design**: Use Pydantic models for validation. Document endpoints with docstrings. Return meaningful error messages.
|
|
|
|
**Testing**: Write tests for new features. Use mocks for external API calls. Maintain test coverage.
|