{"id":49551267,"url":"https://github.com/prasenjit-net/smart-home-assistant","last_synced_at":"2026-05-02T22:35:09.451Z","repository":{"id":322784913,"uuid":"1090868177","full_name":"prasenjit-net/smart-home-assistant","owner":"prasenjit-net","description":"AI-powered smart home assistant using NestJS and OpenAI Agents SDK with stateful conversations","archived":false,"fork":false,"pushed_at":"2025-11-06T09:05:24.000Z","size":139,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-06T11:10:49.791Z","etag":null,"topics":["ai-agents","function-calling","nestjs","openai","smart-home","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/prasenjit-net.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-06T08:45:19.000Z","updated_at":"2025-11-06T09:05:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/prasenjit-net/smart-home-assistant","commit_stats":null,"previous_names":["prasenjit-net/smart-home-assistant"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/prasenjit-net/smart-home-assistant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prasenjit-net%2Fsmart-home-assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prasenjit-net%2Fsmart-home-assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prasenjit-net%2Fsmart-home-assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prasenjit-net%2Fsmart-home-assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prasenjit-net","download_url":"https://codeload.github.com/prasenjit-net/smart-home-assistant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prasenjit-net%2Fsmart-home-assistant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32552375,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T22:28:24.418Z","status":"ssl_error","status_checked_at":"2026-05-02T22:28:14.225Z","response_time":132,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","function-calling","nestjs","openai","smart-home","typescript"],"created_at":"2026-05-02T22:35:05.200Z","updated_at":"2026-05-02T22:35:09.445Z","avatar_url":"https://github.com/prasenjit-net.png","language":"TypeScript","funding_links":["https://opencollective.com/nest"],"categories":[],"sub_categories":[],"readme":"# Smart Home Assistant with OpenAI Agents SDK\n\nA smart home assistant built with NestJS that uses OpenAI's Agents SDK with function calling to control smart home devices through text or audio commands. Supports both **mock JSON database** and **real Home Assistant integration**.\n\n## ✨ Features\n\n- 🏠 **Smart Home Control**: Manage lights, thermostats, door locks, fans, and sensors\n- 🤖 **AI-Powered Agent**: Uses OpenAI Agents SDK with GPT-4o and 14 function tools\n- 🔄 **Stateful Conversations**: Remembers context across commands using OpenAI Conversations API\n- 💬 **Text Commands**: Natural language commands via REST API\n- 🎤 **Audio Commands**: Browser-based audio recording with Whisper API transcription\n- 🏡 **Home Assistant Integration**: Connect to your real Home Assistant instance\n- 📊 **Device State Management**: Track device states, areas, and sensor readings\n- 💾 **Dual Mode**: Use JSON database for demos or Home Assistant for real devices\n\n## 🏗️ Architecture\n\n### Two Data Source Modes\n\n1. **JSON Database Mode** (Default): Mock devices for testing and demos\n2. **Home Assistant Mode**: Control real devices via Home Assistant REST API\n\n### Project Structure\n\n```\nsrc/\n├── models/              # TypeScript interfaces for devices, sensors, and states\n├── database/            # JSON-based database service (mock mode)\n├── homeassistant/       # Home Assistant API integration\n│   ├── homeassistant.service.ts    # HA REST API client\n│   ├── entity-mapper.service.ts    # Convert HA entities to Device models\n│   └── homeassistant.types.ts      # HA type definitions\n├── smarthome/           # Smart home device management (dual-mode)\n├── agent/              # OpenAI Agents SDK with 14 function tools\n├── assistant/          # API controllers and module\n└── main.ts             # Application entry point\n```\n\n## 📦 Installation\n\n1. Clone the repository and install dependencies:\n\n```bash\ngit clone https://github.com/prasenjit-net/smart-home-assistant.git\ncd smart-home-assistant\nnpm install\n```\n\n2. Configure environment variables:\n\nCopy `.env.example` to `.env`:\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` and add your configuration:\n\n```env\n# OpenAI API Key (Required)\nOPENAI_API_KEY=sk-your-actual-api-key-here\n\n# Home Assistant Configuration (Optional - for real device control)\nHOME_ASSISTANT_URL=https://your-ha-instance.com\nHOME_ASSISTANT_TOKEN=your_long_lived_access_token_here\n\n# Feature Flag: Use Home Assistant or JSON Database\nUSE_HOME_ASSISTANT=false  # Set to true to use Home Assistant\n```\n\n### Getting a Home Assistant Token\n\n1. Go to your Home Assistant profile: `https://your-ha-instance.com/profile`\n2. Scroll to \"Long-Lived Access Tokens\"\n3. Click \"Create Token\"\n4. Give it a name like \"Smart Home Assistant AI\"\n5. Copy the token to your `.env` file\n\n## 🚀 Running the Application\n\n```bash\n# Development mode with auto-reload\nnpm run start:dev\n\n# Production mode\nnpm run start:prod\n\n# Build only\nnpm run build\n```\n\nThe server will start on `http://localhost:3000`\n\n## 🌐 Web Interface\n\nOpen `http://localhost:3000/index.html` in your browser for an interactive web interface with:\n- Text command input\n- Browser-based audio recording\n- Real-time responses\n- Session management\n- Example commands\n\n## 📡 API Endpoints\n\n### Commands\n\n#### Send Text Command\n```bash\nPOST /assistant/command/text\nContent-Type: application/json\n\n{\n  \"message\": \"Turn on the living room light\",\n  \"sessionId\": \"conv_abc123\"  # Optional - for conversation continuity\n}\n```\n\n#### Send Audio Command\n```bash\nPOST /assistant/command/audio\nContent-Type: multipart/form-data\n\naudio: \u003caudio file\u003e\nsessionId: conv_abc123  # Optional\n```\n\n### Device \u0026 Sensor Information\n\n#### List All Devices\n```bash\nGET /assistant/devices\n```\n\n#### List All Sensors\n```bash\nGET /assistant/sensors\n```\n\n#### List All Areas\n```bash\nGET /assistant/areas\n```\n\n### Health \u0026 Status\n\n#### Health Check\n```bash\nGET /assistant/health\n```\n\n### Home Assistant Integration Endpoints\n\n#### Test HA Connection\n```bash\nGET /assistant/ha/test\n```\n\n#### Get HA Status \u0026 Version\n```bash\nGET /assistant/ha/status\n```\n\n#### List All HA Entities\n```bash\nGET /assistant/ha/entities\n```\n\n## 💡 Example Commands\n\n### Text Commands\n\n```bash\n# Query device status\ncurl -X POST http://localhost:3000/assistant/command/text \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"message\": \"What devices are in the living room?\"}'\n\n# Turn on a light\ncurl -X POST http://localhost:3000/assistant/command/text \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"message\": \"Turn on the living room light\"}'\n\n# Set brightness\ncurl -X POST http://localhost:3000/assistant/command/text \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"message\": \"Set the bedroom lamp to 50% brightness\"}'\n\n# Check temperature\ncurl -X POST http://localhost:3000/assistant/command/text \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"message\": \"What is the temperature in the living room?\"}'\n\n# Lock door\ncurl -X POST http://localhost:3000/assistant/command/text \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"message\": \"Lock the front door\"}'\n\n# Set thermostat\ncurl -X POST http://localhost:3000/assistant/command/text \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"message\": \"Set the thermostat to 24 degrees\"}'\n```\n\n### Audio Commands\n\n```bash\n# Upload an audio file\ncurl -X POST http://localhost:3000/assistant/command/audio \\\n  -F \"audio=@./recording.wav\"\n```\n\n## Sample Smart Home Setup\n\nThe application initializes with the following sample devices:\n\n### Devices\n- **Living Room Ceiling Light** (light-1)\n- **Bedroom Table Lamp** (light-2)\n- **Main Thermostat** (thermostat-1)\n- **Front Door Lock** (lock-1)\n- **Bedroom Ceiling Fan** (fan-1)\n\n### Sensors\n- **Living Room Temperature Sensor** (temp-1)\n- **Bathroom Humidity Sensor** (humid-1)\n- **Garage Motion Sensor** (motion-1)\n\n### Areas\n- Living Room\n- Bedroom\n- Kitchen\n- Bathroom\n- Garage\n\n## 🛠️ AI Function Tools\n\nThe OpenAI agent has access to 14 function tools for smart home control:\n\n### Device Listing\n1. **list_devices** - List all smart home devices\n2. **list_devices_by_area** - List devices in a specific area/room\n3. **list_sensors** - List all sensors\n4. **list_sensors_by_area** - List sensors in a specific area\n5. **list_areas** - List all areas in the home\n\n### Device Status\n6. **get_device_status** - Get current status of a specific device\n7. **get_sensor_status** - Get current sensor reading\n\n### Device Control\n8. **turn_on_device** - Turn on lights, switches, fans\n9. **turn_off_device** - Turn off devices\n10. **set_brightness** - Set light brightness (0-100)\n11. **set_temperature** - Set thermostat temperature\n12. **lock_door** - Lock a door\n13. **unlock_door** - Unlock a door\n14. **set_fan_speed** - Set fan speed (0-100)\n\nAll tools work with both JSON database mode and Home Assistant mode!\n\n## Database\n\nDevice states are persisted in `data/smarthome.json`. This file is automatically created on first run with sample data.\n\n## Technologies Used\n\n- **NestJS** - Progressive Node.js framework\n- **OpenAI API** - GPT-4o for natural language processing and function calling\n- **Whisper API** - Audio transcription\n- **TypeScript** - Type-safe development\n- **Multer** - File upload handling\n\n## Development\n\n```bash\n# Run in development mode with auto-reload\nnpm run start:dev\n\n# Run tests\nnpm run test\n\n# Build for production\nnpm run build\n```\n\n## License\n\nMIT\n\n  \u003c!--[![Backers on Open Collective](https://opencollective.com/nest/backers/badge.svg)](https://opencollective.com/nest#backer)\n  [![Sponsors on Open Collective](https://opencollective.com/nest/sponsors/badge.svg)](https://opencollective.com/nest#sponsor)--\u003e\n\n## Description\n\n[Nest](https://github.com/nestjs/nest) framework TypeScript starter repository.\n\n## Project setup\n\n```bash\n$ npm install\n```\n\n## Compile and run the project\n\n```bash\n# development\n$ npm run start\n\n# watch mode\n$ npm run start:dev\n\n# production mode\n$ npm run start:prod\n```\n\n## Run tests\n\n```bash\n# unit tests\n$ npm run test\n\n# e2e tests\n$ npm run test:e2e\n\n# test coverage\n$ npm run test:cov\n```\n\n## Deployment\n\nWhen you're ready to deploy your NestJS application to production, there are some key steps you can take to ensure it runs as efficiently as possible. Check out the [deployment documentation](https://docs.nestjs.com/deployment) for more information.\n\nIf you are looking for a cloud-based platform to deploy your NestJS application, check out [Mau](https://mau.nestjs.com), our official platform for deploying NestJS applications on AWS. Mau makes deployment straightforward and fast, requiring just a few simple steps:\n\n```bash\n$ npm install -g @nestjs/mau\n$ mau deploy\n```\n\nWith Mau, you can deploy your application in just a few clicks, allowing you to focus on building features rather than managing infrastructure.\n\n## Resources\n\nCheck out a few resources that may come in handy when working with NestJS:\n\n- Visit the [NestJS Documentation](https://docs.nestjs.com) to learn more about the framework.\n- For questions and support, please visit our [Discord channel](https://discord.gg/G7Qnnhy).\n- To dive deeper and get more hands-on experience, check out our official video [courses](https://courses.nestjs.com/).\n- Deploy your application to AWS with the help of [NestJS Mau](https://mau.nestjs.com) in just a few clicks.\n- Visualize your application graph and interact with the NestJS application in real-time using [NestJS Devtools](https://devtools.nestjs.com).\n- Need help with your project (part-time to full-time)? Check out our official [enterprise support](https://enterprise.nestjs.com).\n- To stay in the loop and get updates, follow us on [X](https://x.com/nestframework) and [LinkedIn](https://linkedin.com/company/nestjs).\n- Looking for a job, or have a job to offer? Check out our official [Jobs board](https://jobs.nestjs.com).\n\n## Support\n\nNest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please [read more here](https://docs.nestjs.com/support).\n\n## Stay in touch\n\n- Author - [Kamil Myśliwiec](https://twitter.com/kammysliwiec)\n- Website - [https://nestjs.com](https://nestjs.com/)\n- Twitter - [@nestframework](https://twitter.com/nestframework)\n\n## License\n\nNest is [MIT licensed](https://github.com/nestjs/nest/blob/master/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprasenjit-net%2Fsmart-home-assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprasenjit-net%2Fsmart-home-assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprasenjit-net%2Fsmart-home-assistant/lists"}