{"id":32033310,"url":"https://github.com/zaydabash/the-cognisphere","last_synced_at":"2026-04-29T20:34:49.038Z","repository":{"id":318756986,"uuid":"1075766956","full_name":"zaydabash/the-cognisphere","owner":"zaydabash","description":"A living ecosystem of cognitive agents that evolve language, culture, alliances, and institutions through emergent dynamics.","archived":false,"fork":false,"pushed_at":"2025-11-11T23:56:10.000Z","size":2368,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-12T01:18:20.035Z","etag":null,"topics":["agent-based-modeling","ai","artificial-intelligence","cultural-evolution","emergent-intelligence","fastapi","multi-agent-systems","neo4j","python","react","simulation"],"latest_commit_sha":null,"homepage":"https://zaydabash.github.io/the-cognisphere/","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/zaydabash.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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-10-14T00:57:37.000Z","updated_at":"2025-11-11T23:56:14.000Z","dependencies_parsed_at":"2025-10-15T06:11:56.481Z","dependency_job_id":"3a55daf0-2f73-43f4-9808-015124d82b86","html_url":"https://github.com/zaydabash/the-cognisphere","commit_stats":null,"previous_names":["zaydabash/the-cognisphere"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/zaydabash/the-cognisphere","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaydabash%2Fthe-cognisphere","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaydabash%2Fthe-cognisphere/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaydabash%2Fthe-cognisphere/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaydabash%2Fthe-cognisphere/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zaydabash","download_url":"https://codeload.github.com/zaydabash/the-cognisphere/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaydabash%2Fthe-cognisphere/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32443563,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T20:22:27.477Z","status":"ssl_error","status_checked_at":"2026-04-29T20:22:26.507Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["agent-based-modeling","ai","artificial-intelligence","cultural-evolution","emergent-intelligence","fastapi","multi-agent-systems","neo4j","python","react","simulation"],"created_at":"2025-10-17T02:12:55.439Z","updated_at":"2026-04-29T20:34:49.030Z","avatar_url":"https://github.com/zaydabash.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# The Cognisphere: Emergent Intelligence Civilization Engine\n\n[![CI](https://github.com/zaydabash/the-cognisphere/actions/workflows/ci.yml/badge.svg)](https://github.com/zaydabash/the-cognisphere/actions/workflows/ci.yml)\n[![Release](https://github.com/zaydabash/the-cognisphere/actions/workflows/release.yml/badge.svg)](https://github.com/zaydabash/the-cognisphere/actions/workflows/release.yml)\n[![Pages](https://img.shields.io/badge/Deploy-GitHub%20Pages-222)](https://github.com/zaydabash/the-cognisphere/deployments/activity_log?environment=github-pages)\n[![Backend](https://img.shields.io/badge/Deploy-Render-2b2b2b)](https://dashboard.render.com/)\n[![Containers](https://img.shields.io/badge/Containers-Docker%20Ready-blue)](https://github.com/zaydabash/the-cognisphere/pkgs/container/cognisphere)\n\nA living ecosystem of cognitive agents that evolve language, culture, alliances, and institutions through emergent dynamics.\n\n## Architecture Overview\n\n```mermaid\ngraph TB\n    subgraph \"Frontend Layer\"\n        UI[React Dashboard]\n        VIZ[Real-time Visualization]\n        CTRL[Control Panel]\n    end\n    \n    subgraph \"Backend Layer\"\n        API[FastAPI Server]\n        SIM[Simulation Engine]\n        SCHED[Scheduler]\n    end\n    \n    subgraph \"Agent System\"\n        AGENTS[Cognitive Agents]\n        MEMORY[Memory Layer]\n        CULTURE[Cultural Evolution]\n        ECONOMY[Economic System]\n    end\n    \n    subgraph \"Environmental Stimuli\"\n        RSS[RSS Feeds]\n        NEWS[News APIs]\n        WEATHER[Weather Data]\n        SENTIMENT[Sentiment Analysis]\n    end\n    \n    subgraph \"Data Storage\"\n        GRAPH[Graph Database]\n        VECTOR[Vector Storage]\n        EVENTS[Event History]\n    end\n    \n    subgraph \"Deployment\"\n        PAGES[GitHub Pages]\n        RENDER[Render.com]\n        GHCR[GitHub Container Registry]\n    end\n    \n    UI --\u003e API\n    VIZ --\u003e API\n    CTRL --\u003e API\n    \n    API --\u003e SIM\n    SIM --\u003e SCHED\n    SCHED --\u003e AGENTS\n    \n    AGENTS --\u003e MEMORY\n    AGENTS --\u003e CULTURE\n    AGENTS --\u003e ECONOMY\n    \n    MEMORY --\u003e GRAPH\n    MEMORY --\u003e VECTOR\n    SIM --\u003e EVENTS\n    \n    RSS --\u003e SENTIMENT\n    NEWS --\u003e SENTIMENT\n    WEATHER --\u003e SENTIMENT\n    SENTIMENT --\u003e SIM\n    \n    API --\u003e PAGES\n    API --\u003e RENDER\n    SIM --\u003e GHCR\n```\n\n## Live Dashboard Screenshots\n\n### Main Dashboard\nThe central command center showing real-time metrics and civilization overview:\n\n![Dashboard Main](docs/screenshots/dashboard-with-data.png)\n\n## Key Features Showcase\n\n### Environmental Stimuli Integration\n- **Real-world Data**: RSS feeds from BBC, CNN, technology, science, and business sources\n- **Cultural Mirroring**: Agents reflect 70% of real-world events in their culture\n- **Divergence Evolution**: 1% cultural drift creates unique \"future version\" of civilization\n- **Sentiment Analysis**: Emotional impact processing of environmental events\n\n### Multi-Agent Intelligence\n- **Cognitive Architecture**: Each agent has unique personality traits (OCEAN model)\n- **Memory Systems**: Graph-based relationships + vector-based semantic memory\n- **Learning \u0026 Adaptation**: Agents evolve strategies based on experience\n- **Social Dynamics**: Trust, betrayal, alliance formation, and faction creation\n\n### Real-time Visualization\n- **Network Graphs**: Interactive agent relationship visualization\n- **Cultural Timeline**: Myth creation and norm evolution tracking\n- **Economic Charts**: Trade activity, resource distribution, wealth inequality\n- **Language Drift**: Slang evolution and communication pattern analysis\n\n## About The Cognisphere\n\nThe Cognisphere is an experimental simulation platform that explores emergent intelligence through multi-agent systems. It creates a digital civilization where hundreds to thousands of cognitive agents interact, learn, and evolve complex social structures without predetermined scripts.\n\n### What Makes It Unique\n\n**Emergent Intelligence**: Unlike traditional simulations with hard-coded behaviors, The Cognisphere agents develop their own strategies, relationships, and cultural norms through interaction and experience.\n\n**Cultural Evolution**: Agents create myths, develop slang, establish social norms, and form institutions that persist and evolve over time. Language itself drifts and mutates as agents communicate.\n\n**Economic Dynamics**: A fully functional economy emerges from agent interactions, including trade negotiations, resource management, market dynamics, and wealth distribution patterns.\n\n**Social Complexity**: Agents form alliances, betray each other, create factions, and build institutions. Trust relationships evolve based on past interactions and reputation.\n\n**Real-time Visualization**: Watch the civilization unfold through interactive network graphs, cultural timelines, economic indicators, and agent behavior patterns.\n\n### Core Concepts\n\n**Agent Personality**: Each agent has a unique personality profile (based on OCEAN traits) that influences their behavior, decision-making, and social interactions.\n\n**Memory Systems**: Agents maintain episodic memory (events), semantic memory (concepts), and social memory (relationships) using graph and vector databases.\n\n**Cultural Transmission**: Ideas, myths, and norms spread through the population via social networks, creating cultural evolution patterns.\n\n**Economic Emergence**: Trade relationships, resource scarcity, and market dynamics emerge naturally from agent needs and interactions.\n\n**Institutional Formation**: Agents can create lasting institutions like councils, temples, and governance systems that persist beyond individual lifespans.\n\n### Applications\n\n**Research**: Study emergent behavior, cultural evolution, economic dynamics, and social network formation.\n\n**Education**: Understand complex systems, agent-based modeling, and emergent intelligence concepts.\n\n**Entertainment**: Watch fascinating civilizations develop, collapse, and evolve in unexpected ways.\n\n**AI Development**: Explore how simple rules can lead to complex, intelligent-seeming behaviors.\n\n### Technical Innovation\n\nThe Cognisphere combines cutting-edge technologies:\n- **Graph Databases** (Neo4j) for relationship modeling\n- **Vector Databases** (FAISS) for semantic memory\n- **Real-time Visualization** with interactive network graphs\n- **Scalable Architecture** supporting thousands of agents\n- **Deterministic Simulation** for reproducible research\n- **Live Dashboard** for real-time monitoring\n\n## Overview\n\nThe Cognisphere simulates a digital civilization with hundreds to thousands of lightweight cognitive agents who:\n- Evolve language, culture, alliances, norms, and mythology\n- Maintain collective memory over simulated decades\n- Negotiate, trade, betray, form factions, and build institutions\n- React to real-world environmental stimuli\n- Produce emergent structure without hard-coded scripts\n\n## Architecture\n\n```\n        \n   Frontend             Backend              Memory        \n   React + Vite     FastAPI          Neo4j + FAISS \n   Visualization        Simulation           Graph + Vector\n        \n```\n\n## Quick Start\n\n### Option 1: Interactive Setup (Recommended)\n```bash\n# Clone and setup\ngit clone \u003cyour-repo-url\u003e\ncd the-cognisphere\n\n# Run the interactive quick-start script\nchmod +x scripts/quick-start.sh\n./scripts/quick-start.sh\n```\n\n### Option 2: Direct Deployment\n```bash\n# Local Development (uses cognisphere.dev domain)\nchmod +x scripts/local-dev.sh\n./scripts/local-dev.sh\n\n# Docker Development (uses cognisphere.local domain)\ndocker-compose -f docker/docker-compose.yml up --build\n\n# Production Deployment (uses cognisphere.local with SSL)\nchmod +x scripts/deploy.sh\n./scripts/deploy.sh\n```\n\n### Option 3: One-Command Docker\n```bash\n# Quick Docker setup\ndocker-compose -f docker/docker-compose.yml up --build -d\n\n# Run a simulation\npython scripts/seed_and_run.py --preset lab --ticks 300 --seed 42\n```\n\n## Access URLs (No Localhost Issues!)\n\n- **Frontend Dashboard**: `http://cognisphere.local:5173` or `https://cognisphere.local`\n- **API Documentation**: `http://cognisphere.local:8000/api/docs`\n- **Neo4j Browser**: `http://cognisphere.local:7474`\n- **Monitoring**: `http://cognisphere.local:3001` (Grafana)\n\n## Core Features\n\n### Agent Cognitive Architecture\n- Personality vectors (OCEAN-style)\n- Trust calculus and relationship weights\n- Ideology vectors for soft alignment\n- Language lexicons with drifting slang\n- Episodic, semantic, and social memory\n- Internal deliberation with RAG from memory graph\n\n### Economy \u0026 Social Dynamics\n- Resource-based economy (food, energy, artifacts, influence)\n- Bilateral negotiation with alternating offers\n- Market fallback with double auction clearing\n- Alliance/betrayal mechanics with reputation systems\n- Faction dynamics and institution formation\n\n### Cultural Evolution\n- Language drift with slang mutation and JSD divergence tracking\n- Myth generation and canonization\n- Norm voting systems with soft penalties\n- Cultural diffusion modeled as contagion\n\n### Memory Layer\n- Neo4j graph database for relationships and knowledge\n- FAISS vector store for semantic retrieval\n- Snapshot/rewind capability for time travel\n- Deterministic seeded runs for reproducibility\n\n## Dashboard Features\n\n- Real-time agent network visualization\n- Culture timeline with myths, slang, and norms\n- Resource and economy panels\n- Slang divergence plots\n- Simulation control with play/pause/seed\n- Snapshot playback capabilities\n\n## Testing \u0026 Benchmarks\n\n### Test Coverage\n\nThe Cognisphere maintains **70%+ test coverage** via pytest with comprehensive unit and integration tests:\n\n```bash\n# Run test suite with coverage\ncd backend\npython -m pytest --cov=simulation --cov=adapters --cov-report=term-missing --cov-report=html tests/\n\n# View coverage report\nopen htmlcov/index.html\n```\n\n**Test Coverage Details:**\n- **Unit Tests**: Agent behavior, culture evolution, economy dynamics\n- **Integration Tests**: Simulation engine, memory systems, API endpoints\n- **Performance Tests**: Benchmark simulations with 500+ agents\n- **Security Tests**: Input validation, path traversal prevention, CORS configuration\n\n**Coverage Targets:**\n- Core simulation logic: 80%+\n- API endpoints: 75%+\n- Memory systems: 70%+\n- Overall project: 70%+\n\n### Code Quality\n\nThe project uses multiple linting and formatting tools:\n\n```bash\n# Linting with flake8\nflake8 backend/\n\n# Type checking with mypy\nmypy backend/\n\n# Formatting with black\nblack backend/\n\n# Import sorting with isort\nisort backend/\n```\n\n**Quality Standards:**\n- **Flake8**: Code style and complexity checks\n- **MyPy**: Static type checking\n- **Black**: Consistent code formatting\n- **Pytest**: Comprehensive test coverage\n- **Pre-commit**: Automated quality checks\n\n### Performance Benchmarks\n\n```bash\n# Performance benchmark\npython scripts/seed_and_run.py --preset lab --ticks 300\n\n# Determinism check\npython scripts/seed_and_run.py --seed 42 --ticks 100\n```\n\n## Production Deployment\n\n### Quick Setup\n\n1. **Backend (Render.com)**:\n   - Set `ENVIRONMENT=production`\n   - Set `CORS_ORIGINS` to your frontend URLs\n   - Optionally enable authentication with `API_KEY` and `REQUIRE_AUTH=true`\n\n2. **Frontend (GitHub Pages)**:\n   - Set `VITE_API_URL` to your backend URL\n   - HTTPS is automatically enabled\n\nSee [PRODUCTION_SETUP.md](./PRODUCTION_SETUP.md) for detailed instructions.\n\n### Environment Variables\n\n**Backend**:\n- `ENVIRONMENT=production` - Enables production mode\n- `CORS_ORIGINS` - Comma-separated list of allowed origins\n- `API_KEY` - API key for authentication (optional)\n- `REQUIRE_AUTH` - Enable/disable authentication\n\n**Frontend**:\n- `VITE_API_URL` - Backend API URL\n\n## Security\n\n### Security Features\n\nThe Cognisphere implements comprehensive security measures:\n\n#### Input Validation\n- **Pydantic Models**: All API inputs validated with type checking and constraints\n- **Path Traversal Prevention**: Snapshot and file paths validated to prevent directory traversal attacks\n- **Action Validation**: Simulation actions validated against whitelist\n- **Range Validation**: All numeric inputs validated with min/max constraints\n\n#### CORS Configuration\n- **Environment-Based**: CORS origins restricted in production, open in development\n- **Configurable**: Set `CORS_ORIGINS` environment variable for production\n- **Secure Defaults**: Only allows specific HTTP methods (GET, POST, PUT, DELETE, OPTIONS)\n\n#### Error Handling\n- **Security-Aware**: Error messages don't leak internal details in production\n- **Proper HTTP Status Codes**: Uses appropriate status codes (400, 401, 403, 404, 500)\n- **Exception Handling**: Global exception handler prevents information disclosure\n\n#### Environment Variables\n- **No Hardcoded Secrets**: All sensitive data stored in environment variables\n- **`.env.example` Files**: Example files provided without actual secrets\n- **Gitignore Protection**: All `.env` files and secrets directories excluded from version control\n\n### Security Best Practices\n\n1. **Never commit secrets**: All `.env` files and secrets are in `.gitignore`\n2. **Use environment variables**: Store API keys, tokens, and credentials in environment variables\n3. **Restrict CORS in production**: Set `CORS_ORIGINS` environment variable for production deployment\n4. **Validate all inputs**: All API endpoints validate inputs with Pydantic models\n5. **Use HTTPS in production**: Always use HTTPS for production deployments\n6. **Regular updates**: Keep dependencies updated to patch security vulnerabilities\n\n### Security Audit\n\nThe project has been audited for common security issues:\n\n- ✅ **No hardcoded credentials**: All secrets use environment variables\n- ✅ **No `eval()` or `exec()`**: No dangerous code execution patterns\n- ✅ **Input validation**: All inputs validated and sanitized\n- ✅ **Path traversal protection**: File paths validated to prevent attacks\n- ✅ **CORS configuration**: Properly configured for production\n- ✅ **Error handling**: Security-aware error messages\n- ✅ **Dependency security**: Regular dependency updates\n\n### Reporting Security Issues\n\nIf you discover a security vulnerability, please report it responsibly:\n\n1. **Email**: [security@example.com] (replace with your security contact)\n2. **Do not** open a public GitHub issue\n3. **Include**: Description, steps to reproduce, potential impact\n4. **Response**: We will respond within 48 hours\n\n## Configuration\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `AGENTS` | 300 | Number of agents in simulation |\n| `SEED` | 42 | Random seed for reproducibility |\n| `TICK_MS` | 100 | Milliseconds per simulation tick |\n| `LLM_MODE` | mock | LLM mode: mock or openai |\n| `MEM_BACKEND` | neo4j | Memory backend: neo4j or networkx |\n| `VEC_BACKEND` | faiss | Vector backend: faiss or chroma |\n\n## Project Structure\n\n```\ncognisphere/\n backend/           # FastAPI simulation engine\n frontend/          # React dashboard\n docker/            # Containerization\n scripts/           # Utilities and seeding\n data/              # Sample stimuli and configs\n README.md          # This file\n```\n\n## Acceptance Criteria\n\n- One-command startup with Docker Compose\n- Working dashboard with emergent myths, slang, alliances\n- Deterministic seeded runs\n- 500+ agent mock runs on laptop\n- Beautiful, clean architecture \u0026 documentation\n\n## Deployment\n\n### Live Deployment\n\n**Frontend (GitHub Pages)**: [https://zaydbashir.github.io/the-cognisphere](https://zaydbashir.github.io/the-cognisphere)\n\n**Backend (Render)**: ⚠️ **Not yet connected** - See [RENDER_SETUP_CHECKLIST.md](./RENDER_SETUP_CHECKLIST.md) for setup instructions\n\n**Status**: \n- ✅ Configuration files ready (`render.yaml`, deployment workflow)\n- ❌ Render service not created yet\n- ❌ GitHub secrets not configured\n\n**To connect**: Follow the [Render Setup Checklist](./RENDER_SETUP_CHECKLIST.md) to create the service and configure deployment.\n\n### Docker Images\n\n```bash\n# Pull latest images\ndocker pull ghcr.io/zaydbashir/cognisphere-backend:latest\ndocker pull ghcr.io/zaydbashir/cognisphere-frontend:latest\n\n# Run with Docker Compose\ndocker-compose up -d\n```\n\n### Environment Configuration\n\nCopy the example environment files and configure:\n\n```bash\n# Backend\ncp backend/.env.example backend/.env\n\n# Frontend  \ncp frontend/.env.example frontend/.env.local\n```\n\n### Release Process\n\n1. **Tag a release**: `git tag v0.1.0 \u0026\u0026 git push origin v0.1.0`\n2. **Automatic builds**: Docker images pushed to GHCR\n3. **Auto-deploy**: Frontend to GitHub Pages, Backend to Render\n4. **Health checks**: Automated deployment verification\n\n### CI/CD Pipeline\n\n- **Continuous Integration**: Lint, type-check, tests on every push\n- **Release Automation**: Build and push Docker images on tags\n- **Auto-Deployment**: Frontend (GitHub Pages) + Backend (Render)\n- **Health Monitoring**: Automated deployment verification\n\n## License\n\nMIT License - See LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzaydabash%2Fthe-cognisphere","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzaydabash%2Fthe-cognisphere","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzaydabash%2Fthe-cognisphere/lists"}