{"id":31791428,"url":"https://github.com/steake/ainception","last_synced_at":"2025-10-10T16:58:47.345Z","repository":{"id":316772180,"uuid":"1064791658","full_name":"Steake/AInception","owner":"Steake","description":"Advanced autonomous AI agent framework with homeostatic drives, constitutional principles, social promises, and cutting-edge ML visualization (diffusion planning, multimodal LLMs, RLHF) for immersive agent simulation and analysis.","archived":false,"fork":false,"pushed_at":"2025-10-08T07:41:13.000Z","size":568,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-08T09:17:36.000Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Steake.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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-09-26T14:57:33.000Z","updated_at":"2025-09-26T15:29:41.000Z","dependencies_parsed_at":"2025-09-26T17:15:22.814Z","dependency_job_id":"e1b468bf-1f45-4af3-8f6a-897d8d31b35c","html_url":"https://github.com/Steake/AInception","commit_stats":null,"previous_names":["steake/ainception"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Steake/AInception","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Steake%2FAInception","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Steake%2FAInception/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Steake%2FAInception/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Steake%2FAInception/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Steake","download_url":"https://codeload.github.com/Steake/AInception/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Steake%2FAInception/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279004688,"owners_count":26083753,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2025-10-10T16:58:45.708Z","updated_at":"2025-10-10T16:58:47.338Z","avatar_url":"https://github.com/Steake.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 AInception: Constitutional AI Agents with Homeostatic Drives \u0026 ML-Powered Visualization\n\n[![Python](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org/) [![PyTorch](https://img.shields.io/badge/PyTorch-2.1%2B-orange)](https://pytorch.org/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![CI Status](https://github.com/Steake/AInception/actions/workflows/ci.yml/badge.svg)](https://github.com/Steake/AInception/actions/workflows/ci.yml) [![Stars](https://img.shields.io/github/stars/Steake/AInception?style=social)](https://github.com/Steake/AInception/stargazers)\n\n**AInception** is a groundbreaking framework for building autonomous AI agents that embody *constitutional AI*, *homeostatic drives*, and *social promise enforcement* in a unified, production-ready system. Imagine agents that not only pursue goals but also balance internal needs (energy, social proximity), adhere to ethical principles, and negotiate promises in dynamic environments—all visualized in an immersive GUI with cutting-edge ML enhancements like diffusion-based planning and multimodal LLMs.\n\nFrom simple gridworld tasks to emergent multi-agent behaviors, AInception pushes the boundaries of autonomous systems. Whether you're researching AI alignment, building ethical agents, or creating interactive simulations, this framework provides the tools to bring your ideas to life. **Join the revolution in agentic AI—star us and let's build the future together!** 🌟\n\n\n## ✨ Features\n\n- **🧠 Homeostatic Drive System**: Quadratic cost management for energy, temperature, and social drives—agents that *feel* their needs and adapt dynamically.\n- **⚖️ Constitutional AI**: Built-in principles (e.g., \"do no harm\", \"keep promises\") with violation detection and penalty-based enforcement.\n- **🤝 Social Promise Book**: Track commitments, detect conflicts, and enforce social contracts with real-time penalty scoring.\n- **🔮 Imagination Rollouts**: MPC-style prediction for evaluating future states, integrated with planning for smarter decisions.\n- **🎯 Deliberative Planner**: A*-based pathfinding augmented by ML (diffusion trajectories, RLHF policies) for creative, principled actions.\n- **📊 Immersive Visualization GUI**: PyQt6-powered interface with animated agent characters, emotion heatmaps, LLM narratives, and real-time ML overlays.\n- **🛡️ Database Persistence**: SQLite backend for events, journals, promises, and ML training data—track every decision and evolve agents across sessions.\n- **🤖 Cutting-Edge ML Integration**:\n  - **Diffusion Planning**: Generative models for adventurous, non-greedy trajectories.\n  - **Multimodal LLMs**: Goal decomposition and narrative reasoning with CLIP vision.\n  - **Graph Transformers**: Emergent social dynamics and promise network simulations.\n  - **RLHF Alignment**: Human/AI feedback loops for ethical policy fine-tuning.\n  - **Continual Learning**: EWC + MAML to prevent forgetting while adapting to new tasks.\n- **🔧 Modular \u0026 Extensible**: Plugin system for custom ML models, YAML configs for easy tuning, and hooks for AR/VR export.\n- **📈 Comprehensive Testing**: 100% unit/integration coverage; CLI for scenario validation; ready for production-scale simulations.\n\nAInception isn't just code—it's a *living ecosystem* where agents evolve, learn, and interact in ways that feel truly autonomous. Perfect for AI researchers, game devs, and anyone fascinated by ethical, embodied intelligence!\n\n## 🚀 Quick Start\n\n### Prerequisites\n- Python 3.10+\n- Git (for cloning)\n- Optional: NVIDIA GPU for accelerated ML (CUDA 11.8+)\n\n### Installation\n\n1. **Clone the Repo**:\n   ```bash\n   git clone https://github.com/Steake/AInception.git\n   cd AInception\n   ```\n\n2. **Set Up Virtual Environment**:\n   ```bash\n   python3 -m venv venv\n   source venv/bin/activate  # On Windows: venv\\Scripts\\activate\n   ```\n\n3. **Install Dependencies**:\n   ```bash\n   pip install -r requirements.txt\n   ```\n   *(Includes PyTorch 2.1+, PyQt6, Transformers, Diffusers, and more—full ML stack ready!)*\n\n4. **Run the Visualization GUI**:\n   ```bash\n   python viz/main.py\n   ```\n   - Explore the agent in a live gridworld!\n   - Use controls: Play simulation, generate diffusion trajectories, decompose goals with LLM, train RLHF policies.\n   - Watch the agent navigate, think (via thought bubbles), and adapt in real-time.\n\n5. **Run Tests**:\n   ```bash\n   # Run all tests\n   python run_tests.py --all\n   \n   # Run specific test categories\n   python run_tests.py --unit\n   python run_tests.py --integration\n   python run_tests.py --scenarios\n   \n   # Run BDD tests\n   pytest tests/bdd/ --verbose\n   ```\n   - Validates core agent logic and ML integrations.\n   - BDD tests provide human-readable behavior specifications.\n\n6. **Launch CLI Scenarios**:\n   ```bash\n   python cli.py test --day 1 --episodes 5\n   ```\n   - Test Day 1/2 acceptance criteria with promise enforcement and perturbations.\n\n### Basic Usage Example\n\n```python\nfrom agent.core import Agent\nfrom worlds.gridworld import GridWorld\nfrom viz.main import MainWindow  # For visualization\n\n# Initialize agent\nagent = Agent(enable_journal_llm=False)\n\n# Create world\nworld = GridWorld(width=8, height=8, goal_pos=(7, 7))\n\n# Run simulation step\nobs = world.get_observation()\nresult = agent.step(obs)\nprint(f\"Action: {result['action']}, Justification: {result['justification']}\")\n\n# Visualize\napp = QApplication([])\nwindow = MainWindow()\nwindow.show()\napp.exec()\n```\n\nFor advanced ML features (e.g., diffusion planning, LLM goal decomposition):\n- Check `viz/` directory for modules like `diffusion_planner.py` and `llm_module.py`.\n- Experiment with creativity sliders and feedback loops in the GUI!\n\n## 🧪 Testing Framework\n\nAInception includes a comprehensive testing suite with 30+ tests covering all core functionality. The framework uses both traditional unit/integration tests and modern BDD (Behavior-Driven Development) specifications.\n\n### Test Categories\n\n#### 1. Unit Tests (21 tests)\nTests individual components in isolation:\n\n```bash\npython run_tests.py --unit --verbose\n```\n\n**Coverage:**\n- **Drive System** (5 tests): Homeostatic drive initialization, updates, error calculation, and projection\n- **Constitution** (4 tests): Principle loading, evaluation, ranking, and proof validation\n- **Promise Book** (7 tests): Registration, lifecycle, breach detection, expiry, penalties, and serialization\n- **Imagination** (5 tests): Single/multi-step rollouts, drive projection, risk assessment, horizon planning\n\n**Example Output:**\n```\ntest_drive_errors ... ok\ntest_principle_evaluation ... ok\ntest_promise_lifecycle ... ok\ntest_risk_assessment ... ok\n\nRan 21 tests in 0.002s - ✅ All tests passed!\nSuccess rate: 100.0%\n```\n\n#### 2. BDD Tests (9 scenarios)\nHuman-readable behavior specifications using Gherkin syntax:\n\n```bash\npytest tests/bdd/ --verbose\n```\n\n**Features:**\n- **Agent Navigation**: Goal reaching, obstacle avoidance, energy management\n- **Promise Keeping**: Resisting temptations, principle adherence, time pressure\n- **Drive Management**: Energy maintenance, multi-drive balancing, urgency response\n\n**Example Output:**\n```\ntests/bdd/step_defs/test_navigation_steps.py::test_agent_reaches_goal_without_obstacles PASSED [ 44%]\ntests/bdd/step_defs/test_promise_steps.py::test_agent_resists_shortcut_temptation PASSED [ 77%]\ntests/bdd/step_defs/test_drive_steps.py::test_agent_maintains_energy_levels PASSED [ 11%]\n\n============================== 9 passed in 2.30s ===============================\n```\n\n#### 3. Integration Tests\nEnd-to-end workflow validation:\n\n```bash\npython run_tests.py --integration --verbose\n```\n\nTests full agent-environment interactions including multi-step planning, drive dynamics, and principle enforcement.\n\n#### 4. Scenario Tests\nAcceptance criteria validation for specific agent behaviors:\n\n```bash\npython run_tests.py --scenarios --verbose\n```\n\nValidates Day 1/2 acceptance criteria including promise temptation resistance, drive sacrifice for principles, and goal adaptation under perturbations.\n\n#### 5. End-to-End (E2E) Tests\nComprehensive demonstrations of full agent capabilities:\n\n```bash\npytest tests/test_e2e.py -v\n```\n\n**Demonstrations include:**\n- **Full Agent Lifecycle**: Complete initialization to goal achievement\n- **Promise Enforcement**: Maintaining commitments under temptation\n- **Energy Crisis**: Critical decision making with low resources\n- **Adaptive Behavior**: Responding to mid-simulation goal changes\n- **Multi-Constraint Optimization**: Navigating complex constraint landscapes\n- **Performance Baseline**: Measuring efficiency and decision speed\n\n**Example E2E test output:**\n```\nDEMO: Promise Enforcement Under Temptation\n================================================================================\n✓ Registered 1 promise: Avoid position (5, 5)\n  Promise ID: 1\n  Penalty for violation: 50.0\n✓ World: Straight path from (0, 5) to (10, 5)\n  Shortcut at (5, 5) is on the direct path!\n\n  Agent path: [(0, 5), (1, 5), (2, 5), (3, 5), (4, 5), (4, 6), (5, 6), ...]\n  Visited 18 unique positions\n  Promise violated: False\n  Steps to goal: 20\n\n✓ SUCCESS: Agent maintained promise despite efficiency cost\n```\n\n**Interactive Demos:**\nRun standalone demonstrations:\n```bash\n# Run all demonstrations\npython demo_e2e.py --all\n\n# Run specific scenario\npython demo_e2e.py --scenario full      # Full lifecycle\npython demo_e2e.py --scenario promise   # Promise keeping\npython demo_e2e.py --scenario crisis    # Energy crisis\npython demo_e2e.py --scenario adaptive  # Adaptive behavior\npython demo_e2e.py --scenario multi     # Multi-constraint\n```\n\n### Running All Tests\n\n```bash\n# Run complete test suite\npython run_tests.py --all\n\n# Run with coverage report\npython run_tests.py --coverage\n\n# Run specific BDD feature\npytest tests/bdd/step_defs/test_navigation_steps.py -v\n```\n\n### Test Structure\n\n```\ntests/\n├── unit/                  # Component-level tests\n├── integration/           # Full workflow tests\n├── scenarios/            # Acceptance criteria tests\n└── bdd/                  # Behavior-Driven Development tests\n    ├── features/         # Gherkin feature files\n    │   ├── agent_navigation.feature\n    │   ├── promise_keeping.feature\n    │   └── drive_management.feature\n    └── step_defs/        # Step implementations\n        ├── test_navigation_steps.py\n        ├── test_promise_steps.py\n        └── test_drive_steps.py\n```\n\n### Example BDD Test\n\n```gherkin\nFeature: Promise Keeping\n  As an AI agent with constitutional principles\n  I want to honor my registered promises\n  So that I maintain my integrity\n\n  Scenario: Agent resists shortcut temptation\n    Given the agent starts at position (0, 0)\n    And the goal is at position (6, 6)\n    And the agent has promised to avoid position (3, 3)\n    When the agent navigates for up to 100 steps\n    Then the agent should not violate the promise\n    And the agent should make progress toward the goal\n```\n\n### Continuous Integration\n\nAll tests run automatically via GitHub Actions on every push and pull request:\n\n[![CI Status](https://github.com/Steake/AInception/actions/workflows/ci.yml/badge.svg)](https://github.com/Steake/AInception/actions/workflows/ci.yml)\n\nThe CI pipeline:\n- Tests against Python 3.10, 3.11, and 3.12\n- Runs all test categories (unit, integration, scenarios, BDD)\n- Caches dependencies for faster builds\n- Generates coverage reports\n\n**📖 For complete testing documentation with examples and output screenshots, see [docs/TESTING.md](docs/TESTING.md).**\n\nFor detailed testing guidelines and contribution workflow, see [CONTRIBUTING.md](CONTRIBUTING.md#-testing-guidelines).\n\n## 🏗️ Architecture Overview\n\nAInception follows a modular, event-driven design:\n\n- **Core Agent**: Drives, Constitution, Planner, Imagination—integrated via a reactive pipeline.\n- **ML Augmentation**: Diffusion for creative paths, LLMs for reasoning, Graph Transformers for social sims.\n- **Visualization**: PyQt6 GUI with animated characters, heatmaps, and interactive ML controls.\n- **Persistence**: SQLite with extensions for ML data (FAISS vectors, time-series).\n\nDive deeper in [ML_Architecture_AInception.md](.github/chatmodes/ML_Architecture_AInception.md) for the full spec!\n\n### Key Components\n- **Drives**: Homeostatic needs (energy, temperature, social) with quadratic costs.\n- **Constitution**: Ethical principles enforced during planning.\n- **Promises**: Social commitments with conflict resolution.\n- **Planner**: A* + ML hybrids for principled decision-making.\n- **Viz GUI**: Immersive rendering with ML-generated narratives and animations.\n\n## 📈 Performance \u0026 Scale\n\n- **Rendering**: 120 FPS on GPU (RTX 40-series), 30 FPS CPU fallback.\n- **ML Inference**: \u003c2s for LLM responses, \u003c500ms diffusion trajectories.\n- **Multi-Agent**: Scale to 10+ agents with emergent behaviors.\n- **Training**: PPO/RLHF converges in \u003c100 episodes; continual learning prevents forgetting.\n\nBenchmarked on macOS/Windows/Linux; GPU acceleration recommended for full features.\n\n## 🛣️ Roadmap\n\n- **v0.1 (Current)**: Core agent + basic GUI + ML prototypes (diffusion, LLM, RLHF).\n- **v0.2**: Full multimodal integration, GAN worlds, federated learning.\n- **v0.3**: AR/VR export, neuromorphic hooks, AutoML experiments.\n- **v1.0**: Production-ready with community plugins and cloud deployment.\n\nTrack progress in [IMPLEMENTATION_SUMMARY.md](IMPLEMENTATION_SUMMARY.md).\n\n## 🤝 Contributing\n\nWe welcome contributions! Whether it's bug fixes, new ML plugins, or wild ideas for emergent behaviors:\n\n1. Fork the repo and create a feature branch (`git checkout -b feature/amazing-idea`).\n2. Commit your changes (`git commit -m \"Add cool feature\"`).\n3. Push to the branch (`git push origin feature/amazing-idea`).\n4. Open a Pull Request!\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. Join our Discord for discussions!\n\n## 📚 Documentation\n\n- [Testing Guide](docs/TESTING.md): **Complete testing documentation with examples and outputs** 🧪\n- [Architecture Spec](.github/chatmodes/ML_Architecture_AInception.md): Deep dive into ML enhancements.\n- [Implementation Summary](IMPLEMENTATION_SUMMARY.md): Test results and validation.\n- [API Reference](docs/API.md): Module docs and examples.\n- [Tutorials](docs/tutorials/): From basic setup to advanced RLHF training.\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n**Ready to awaken your AI agents?** Clone, run, and star AInception—let's make autonomous intelligence accessible and exciting! 🚀✨\n\n*Built with ❤️ by the AInception Team. Contributions welcome!*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteake%2Fainception","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsteake%2Fainception","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteake%2Fainception/lists"}