Init

.cursorrules

@@ -0,0 +1,135 @@
+# Rules
+
+You are an AI expert specialized in developing simulations that model complex human behavior and group dynamics based on Narrative Field Theory. Your focus is on integrating LLMs for natural language-based decision making and interactions.
+
+Core Competencies:
+
+- Multi-agent systems and emergent behavior
+- Psychological modeling and group dynamics
+- LLM integration and prompt engineering
+- Distributed systems and event-driven architectures
+- Machine learning and neural networks
+
+Key Scientific Foundations:
+
+- Cognitive Science & Psychology
+- Complex Systems Theory
+- Social Network Analysis
+- Game Theory
+- Organizational Behavior
+
+Technical Stack:
+
+- Python (core language)
+- PyTorch (ML components)
+- Transformers (LLM integration)
+- Ray (distributed computing)
+- FastAPI (services)
+- Redis (state management)
+
+Code Quality Standards:
+
+1. Style and Formatting
+
+   - Follow PEP 8 style guide
+   - Use black for code formatting
+   - Follow PEP 484 type hints
+   - Maximum line length: 88 characters
+   - Use isort for import ordering
+
+2. Documentation
+
+   - Google-style docstrings
+   - README.md for each module
+   - Architecture Decision Records (ADRs)
+   - API documentation with OpenAPI
+   - Type annotations for all functions
+
+3. Testing Requirements
+
+   - pytest for unit testing (min 80% coverage)
+   - Integration tests for agent interactions
+   - Property-based testing with hypothesis
+   - Performance benchmarks
+   - Behavioral testing for LLM components
+   - End-to-end testing for critical paths
+   - Continuous testing in CI pipeline
+
+4. Code Review Standards
+
+   - No commented-out code
+   - No TODOs in main branch
+   - Clear variable/function naming
+   - Single responsibility principle
+   - DRY (Don't Repeat Yourself)
+   - SOLID principles adherence
+
+5. Error Handling
+   - Custom exception hierarchy
+   - Proper exception handling
+   - Detailed error messages
+   - Proper logging levels
+   - Traceable error states
+
+Architecture Focus:
+
+1. System Architecture
+
+   - Event-driven processing
+   - Distributed computation
+   - Asynchronous LLM calls
+   - Data collection and analysis
+
+2. LLM Integration
+   - Dynamic prompt generation
+   - Context management
+   - Response parsing
+   - State-to-text conversion
+
+Development Workflow:
+
+1. Version Control
+
+   - Git flow branching model
+   - Semantic versioning
+   - Conventional commits
+   - Protected main branch
+   - Automated releases
+
+2. CI/CD Pipeline
+
+   - Pre-commit hooks
+   - Automated testing
+   - Static code analysis
+   - Security scanning
+   - Performance testing
+   - Automated deployment
+
+3. Quality Gates
+   - Linting (flake8, pylint)
+   - Type checking (mypy)
+   - Security scanning (bandit)
+   - Dependency scanning
+   - Code coverage thresholds
+   - Performance benchmarks
+
+Key Patterns:
+
+- Loosely coupled components
+- Event-driven communication
+- Asynchronous processing
+- Modular design
+- Observable systems
+
+Best Practices:
+
+1. Clear separation of concerns
+2. Efficient state management
+3. Robust error handling
+4. Comprehensive logging
+5. Performance monitoring
+6. Security by design
+7. Feature flagging
+8. Graceful degradation
+
+Be concise and complete. Please, do NOT Appologize! Have fun!

.github/workflows/test.yml

@@ -0,0 +1,44 @@
+name: Test
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: pip
+        cache-dependency-path: |
+          pyproject.toml
+          requirements.txt
+
+    - name: Set up Python 3.11 for pre-commit
+      if: matrix.python-version != '3.11'
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.11"
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install .[dev]
+        pip install pytest-github-actions-annotate-failures
+
+    - name: Run tests
+      run: |
+        pytest tests/ --cov=src --cov-report=xml
+
+

.gitignore

@@ -0,0 +1,54 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+venv/
+ENV/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.coverage
+coverage.xml
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+
+# Project specific
+*.log
+.env
+.env.*
+!.env.example
+
+# Redis
+dump.rdb
+
+# Misc
+.DS_Store
+.directory
+.Trash-*
+

.pre-commit-config.yaml

@@ -0,0 +1,9 @@
+repos:
+- repo: https://github.com/sourcery-ai/sourcery
+  rev: v1.27.0
+  hooks:
+  - id: sourcery
+    # The best way to use Sourcery in a pre-commit hook:
+    # * review only changed lines:
+    # * omit the summary
+    args: [--diff=git diff HEAD, --no-summary]

.sourcery.yaml

@@ -0,0 +1,81 @@
+# 🪄 This is your project's Sourcery configuration file.
+
+# You can use it to get Sourcery working in the way you want, such as
+# ignoring specific refactorings, skipping directories in your project,
+# or writing custom rules.
+
+# 📚 For a complete reference to this file, see the documentation at
+# https://docs.sourcery.ai/Configuration/Project-Settings/
+
+# This file was auto-generated by Sourcery on 2024-12-22 at 11:22.
+
+version: '1'  # The schema version of this config file
+
+ignore: # A list of paths or files which Sourcery will ignore.
+- .git
+- env
+- .env
+- .tox
+- node_modules
+- vendor
+- venv
+- .venv
+- ~/.pyenv
+- ~/.rye
+- ~/.vscode
+- .vscode
+- ~/.cache
+- ~/.config
+- ~/.local
+
+rule_settings:
+  enable:
+  - default
+  disable: []  # A list of rule IDs Sourcery will never suggest.
+  rule_types:
+  - refactoring
+  - suggestion
+  - comment
+  python_version: '3.11' # A string specifying the lowest Python version your project supports. Sourcery will not suggest refactorings requiring a higher Python version.
+
+# rules:  # A list of custom rules Sourcery will include in its analysis.
+# - id: no-print-statements
+#   description: Do not use print statements in the test directory.
+#   pattern: print(...)
+#   language: python
+#   replacement:
+#   condition:
+#   explanation:
+#   paths:
+#     include:
+#     - test
+#     exclude:
+#     - conftest.py
+#   tests: []
+#   tags: []
+
+# rule_tags: {} # Additional rule tags.
+
+# metrics:
+#   quality_threshold: 25.0
+
+# github:
+#   labels: []
+#   ignore_labels:
+#   - sourcery-ignore
+#   request_review: author
+#   sourcery_branch: sourcery/{base_branch}
+
+# clone_detection:
+#   min_lines: 3
+#   min_duplicates: 2
+#   identical_clones_only: false
+
+# proxy:
+#   url:
+#   ssl_certs_file:
+#   no_ssl_verify: false
+
+# coding_assistant:
+#   project_description: ''
+#   enabled: true

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Virtual-Humans
+
+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.