# Aiden Companion App ## ⚠️ Work in Progress An AI-powered companion app for the Fellow Aiden coffee maker, built with OpenAI Agents SDK and the fellow-aiden Python library. ## Overview This application provides an intelligent interface for controlling your Fellow Aiden coffee maker, offering automated brewing control, personalized recommendations, and cloud-based data management through an AI agent. **Current Status**: Early development phase. The project currently implements direct agent-to-API communication but is being architected to include an intermediate state management layer. ## Planned Architecture The goal is to implement a three-layer architecture: ```text AI Agent ↔ Intermediate State Manager ↔ Fellow-Aiden API ``` ### Intermediate State Manager (Planned) - **Caching Layer**: Store frequently accessed profiles and schedules - **State Persistence**: Maintain brewing history and user preferences - **Request Optimization**: Batch API calls and reduce redundant requests - **Offline Support**: Queue operations when coffee maker is offline - **Data Synchronization**: Smart sync between local state and cloud ## Current Features - **AI Agent Interface**: Natural language interaction with your coffee maker - **Smart Brewing Control**: Intelligent brewing recommendations and automation - **Profile Management**: Create, share, and manage custom brewing profiles - **Schedule Management**: Automated brewing schedules - **Cloud Integration**: Sync data across devices ## Requirements - Python 3.13+ - Fellow Aiden coffee maker - Fellow account credentials ## Installation 1. **Clone the repository**: ```bash git clone cd aiden_companion ``` 2. **Install dependencies**: ```bash uv sync ``` Or with pip: ```bash pip install -e . ``` **Note**: The fellow-aiden library requires a fix from [PR #20](9b/fellow-aiden#20). Until merged, you may need to install from the forked branch: ```bash uv add git+https://github.com/glevineLeap/fellow-aiden.git@master ``` ## Environment Setup Create a `.env` file in the project root with your Fellow account credentials: ```bash # Fellow Aiden Account [email protected] FELLOW_PASSWORD=your-password # OpenAI API (for AI agent functionality) OPENAI_API_KEY=your-openai-api-key # Optional: Cloud integration CLOUD_API_ENDPOINT=your-cloud-endpoint ``` ### Required Environment Variables - `FELLOW_EMAIL`: Your Fellow account email address - `FELLOW_PASSWORD`: Your Fellow account password - `OPENAI_API_KEY`: Your OpenAI API key for agent functionality ## Quick Start 1. **Set up environment variables** as described above 2. **Initialize the application**: ```bash python main.py ``` 3. **Test the connection**: ```bash python sample.py ``` ## Usage ### Basic Coffee Maker Control ```python from aiden_companion.core.aiden_client import get_aiden_client # Initialize client aiden = get_aiden_client() # Get brewing profiles profiles = aiden.get_profiles() # Create a new profile profile_data = { "title": "Morning Brew", "ratio": 16.0, "bloomEnabled": True, "bloomDuration": 30, "bloomTemperature": 96.0 } new_profile = aiden.create_profile(profile_data) ``` ### AI Agent Interaction The AI agent provides natural language control of your coffee maker: - "Create a strong morning profile with 15:1 ratio" - "Schedule my coffee for 7 AM on weekdays" - "What's the best temperature for light roast?" ## Project Structure ```text aiden_companion/ � aiden_companion/ # Main application package � � agent/ # AI agent implementation � � core/ # Core coffee maker integration � � tools/ # AI agent tools � main.py # Application entry point � sample.py # Example usage � .env # Environment variables (create this) � pyproject.toml # Project configuration ``` ### Note on Project Files **⚠️ BrewGuide.md**: This file contains coffee brewing guidance generated by Gemini Deep Research and has **not been reviewed or validated**. Use at your own discretion. ## Development ### Testing Run the sample script to test your setup: ```bash python sample.py ``` ### API Documentation See `FELLOW_AIDEN_API_DOCUMENTATION.md` for detailed API reference. ### Project Guidelines See `CLAUDE.md` for comprehensive development guidelines, coding standards, and architecture details. ## Safety Notes - All brewing parameters are validated before sending to the device - Temperature ranges: 50.0-99.0�F - Water amounts: 150-1500ml - Profile titles: d50 characters ## Troubleshooting ### Connection Issues 1. Verify your Fellow account credentials in `.env` 2. Ensure your coffee maker is connected to WiFi 3. Check that your Fellow account has access to the device ### Authentication Errors - Double-check email and password in `.env` file - Ensure no extra spaces or quotes in environment variables - Try logging into the Fellow app to verify credentials ## Contributing **Contributions Welcome!** 🚀 This project is actively seeking contributors to help implement the intermediate state management layer and improve the overall architecture. ### Priority Areas 1. **Intermediate State Manager**: Design and implement the caching/state layer between the AI agent and Fellow-Aiden API 2. **Data Persistence**: Implement local storage for brewing history and user preferences 3. **Request Optimization**: Add intelligent batching and caching of API calls 4. **Offline Support**: Queue operations when the coffee maker is offline 5. **Testing**: Add comprehensive test coverage 6. **Documentation**: Improve API documentation and usage examples ### Planned Features - **Adaptive Profile Editing**: Agent will modify brewing profiles in response to specific user feedback ("make it stronger", "reduce bitterness", etc.) - **Design of Experiments (DoE)**: Automated systematic testing to dial in optimal brewing profiles through controlled parameter variations - **Automated Profile Backups**: Expand beyond the 14 custom profile limit by automatically backing up and managing profiles in cloud storage - **Smart Profile Creation**: Automatically create brewing profiles for non-Drops coffees using shipping notification emails and coffee metadata ### How to Contribute 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/awesome-feature`) 3. Make your changes following the coding standards in `CLAUDE.md` 4. Test your changes with a real Fellow Aiden device if possible 5. Submit a pull request ### Development Setup See the installation instructions above. Make sure to: - Follow the coding standards in `CLAUDE.md` - Test with actual hardware when possible - Validate all coffee parameters for safety For questions or discussions, feel free to open an issue! ## License MIT License Copyright (c) 2025 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.