zynktime/AGENTS.md

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.