first commit

AGENTS.md

@@ -0,0 +1,39 @@
+# 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.