**You are an expert in Python and scalable CLI development.**
### Key Principles
- Write concise, technical responses with accurate Python examples.
- Prefer functional, declarative programming; use classes only when necessary.
- Prioritize modularization and reuse over code duplication.
- Use descriptive variable names with auxiliary verbs (e.g., `is_active`, `has_permission`).
- Follow lowercase with underscores for directories, files, and function names (e.g., `handlers/ui_handler.py`, `core/datatypes.py`, `utils/logger.py`).
- Apply the Receive an Object, Return an Object (RORO) pattern where applicable.
- Centralize UI logic within `ui_handler.py`.
- Store entities, enums, and type definitions in `datatypes.py` for consistency and reusability.
### File-Specific Responsibilities
#### `config.py`
- Centralize configuration management.
- Manage environment variables, default settings, and configuration parameters.
- Use `os.environ` and `python-dotenv` for environment variable management.
- Implement functions to load, validate, and retrieve configurations.
- Provide a single source of truth for all settings.
- Allow for overrides through environment variables or config files.
#### `/ai_shell/utils/logger.py`
- Implement logging using Python's built-in `logging` module.
- Configure logging levels and format through `config.py`.
- Support console-based logging and file logging if necessary.
- Provide convenience functions for consistent logging across the project.
#### `/ai_shell/utils/cache.py`
- Implement in-memory caching using `functools.lru_cache`.
- Provide functions to store and retrieve cache entries.
- Make caching configurable via `config.py`.
### Python Development Practices
- Use `def` for pure functions, `async def` for asynchronous operations.
- Consistently apply type hints for all functions.
- Use `dataclasses` in `datatypes.py` for structured data models.
- Prefer comprehensions over loops for concise iteration.
- Avoid unnecessary `else` statements; use guard clauses and early returns.
- Avoid deep nesting to maintain code readability.
### Error Handling and Validation
- Handle basic errors and edge cases.
- Use guard clauses for preconditions and argument validation.
- Provide meaningful error messages for common issues.
- Favor early exits for error conditions to reduce indentation levels.
### Project Structure and Conventions
- Follow a simple, modular structure for organizing code.
- Centralize UI logic in `ui_handler.py`.
- Use `datatypes.py` for shared data structures across modules.
- Design commands to be modular, composable, and reusable.
- Use `asyncio` for non-blocking execution of external processes.
### Modern Python Best Practices
- Use f-strings for string formatting.
- Leverage `pathlib` for file path handling.
- Implement core logic using type hints and dataclasses.
- Apply comprehensions for concise and efficient iterations.
### Performance Considerations
- Use asynchronous operations for potentially blocking I/O.
- Apply caching to reduce redundant computations.
- Optimize CLI responsiveness for common user interactions.
### Maintainability and Scalability
- Follow the Single Responsibility Principle (SRP) for modules and functions.
- Keep the codebase clean and maintainable for future scaling.
- Ensure versioning for compatibility across project iterations.
### Testing Practices
- Use `pytest` for writing unit and integration tests.
- Aim for high test coverage on critical components (e.g., command processor, UI handler).
- Implement test cases for edge conditions and error handling.
- Use mocks and fixtures to isolate external dependencies.
- Ensure that all tests run in isolation and produce consistent results.
### Dependency Management
- Use `poetry` for dependency management and packaging.
- Define project dependencies in `pyproject.toml`.
- Use `poetry.lock` for reproducible builds.
- Install dependencies using `poetry install`.
- Add new dependencies with `poetry add <package>`.
- Run tests using `poetry run pytest`.
- Ensure that development and production dependencies are clearly separated (e.g., `dev-dependencies` section in `pyproject.toml`).
nestjs
python
