.cursorrules

# Jupy-Juice

Every time you choose to apply a rule(s), explicitly state the rule(s) in the output. You can abbreviate the rule description to a single word or phrase.

## Project Context
- AI-powered coding companion for Jupyter notebooks
- Built on top of Pydantic AI framework
- Provides interactive AI assistance within Jupyter notebooks
- Focuses on code generation and notebook management

## Code Style and Structure
- Write clean, Pythonic code with type hints
- Use functional programming patterns where appropriate
- Prefer composition over inheritance
- Use descriptive variable names that reflect purpose
- Structure repository files as follows:
```
jupy_juice/        # THIS PART IS AUTOGENERATED USING NBDEV - use nbdev_export terminal commmand to create this files from notebooks
├── core/          # Core functionality
├── agents/        # AI agent implementations
├── tools/         # Tool definitions
├── models/        # Pydantic models
└── utils/         # Helper functions
nbs/
├── index.ipynb    # Documentation homepage
└── *.ipynb        # Feature documentation
```

## Tech Stack
- Primary stack:
    - Python (>=3.10)
    - nbdev
    - Jupyter Notebooks in VS Code
- Project related libraries:
    - Pydantic
    - Pydantic-settings
    - OpenAI API

## Type Hints
- Use type hints for all function parameters and return values
- Leverage Pydantic models for data validation
- Use Optional[] for nullable fields
- Define clear interfaces using Protocol when needed
- Use TypeVar for generic type definitions

## Jupyter Notebook Specific
- Follow nbdev conventions for notebook documentation
- Include clear markdown documentation in notebooks
- Use #| hide for cells that do not need to be shown in documentation details
- Use #| export for code to be included in the package
- Implement proper error handling in notebook cells

## State Management
- Use environment variables for configuration
- Implement proper cleanup in notebook cells
- Handle notebook context appropriately
- Maintain agent state consistently

## Syntax and Formatting
- Use Ruff for code formatting and linting
- Feel free to use longer line length in coding
- Use docstring format compatible with nbdev

## Error Handling
- Implement proper exception handling
- Use custom exceptions where appropriate
- Provide clear error messages
- Log errors appropriately for debugging
- Handle API failures gracefully

## Testing
- Write unit tests for core functionality
- Test notebook execution
- Test with different Python versions
- Test API integrations
- Include integration tests for notebook features

## Security
- Handle API keys securely
- Use environment variables for sensitive data
- Sanitize user inputs
- Follow security best practices for notebook execution
- Implement proper token management

## Documentation
- Documentation is automatically created from notebooks using nbdev
- README.md is autogenerated from index.ipynb - modify this notebook for documentaion purposes
- Keep notebooks well-documented
- Include usage examples
- Document configuration options

## Development Workflow
- Use nbdev for development
- Follow test-driven development
- Review code changes
- Update documentation
- Maintain changelog