Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
175 lines (137 loc) · 7.25 KB

CONTRIBUTING.md

File metadata and controls

175 lines (137 loc) · 7.25 KB
Raw

Contributing to F.R.I.D.A.Y.

F.R.I.D.A.Y. is a 95K-line cognitive AI operating system with 40+ brain modules, 56 tool actions, and a neuroscience-inspired architecture. Contributions are welcome — whether it's fixing a bug, adding a cognitive module, or improving the pipeline.

Quick Start

git clone https://github.com/subhansh-dev/Friday-Autonomous-Cognitive-AI-Operating-System.git
cd Friday-Autonomous-Cognitive-AI-Operating-System
pip install -r requirements.txt
python main.py

Requirements: Python 3.12+, ~4GB RAM, no GPU required.

Architecture Overview

Before contributing, familiarize yourself with the core architecture:

┌─────────────────────────────────────────────────────────┐
│                    COGNITIVE LAYER                       │
│  reason → perceive → plan → simulate → execute →        │
│  debug → reflect → consolidate                          │
├─────────────────────────────────────────────────────────┤
│                    BRAIN MODULES (40+)                   │
│  cognitive_integration │ agi_orchestrator │ intuition    │
│  active_inference      │ causal_reasoner  │ dreaming     │
│  metacognitive_monitor │ emotional_regulation             │
│  self_awareness        │ world_simulation │ code_evolution│
├─────────────────────────────────────────────────────────┤
│                    ACTION LAYER (56 tools)               │
│  code_helper │ browser_control │ security_tools │ ...   │
├─────────────────────────────────────────────────────────┤
│                    MEMORY SYSTEMS                        │
│  neural │ episodic │ vector │ procedural │ associative  │
│  predictive │ consolidation │ global_workspace          │
└─────────────────────────────────────────────────────────┘

Key entry points:

  • main.py — Session loop, tool dispatch, voice I/O
  • brain/cognitive_integration.py — Fast/slow routing (System 1 / System 2)
  • brain/agi_orchestrator.py — Module loader, 17 cognitive stages
  • brain/code_reasoning_engine.py — Design patterns, type inference, contracts
  • skills/cognitive_gating.py — Complexity classifier

How to Contribute

Reporting Bugs

Open an issue with:

  • What happened vs what you expected
  • Steps to reproduce (be specific)
  • Environment: OS, Python version, hardware (webcam, mic, GPU if relevant)
  • Logs: paste the relevant traceback or FRIDAY console output

Suggesting Features

Open an issue with the enhancement label. Describe:

  • The use case — what problem does this solve?
  • How it fits — which brain module or pipeline stage does it affect?
  • Alternatives — have you considered other approaches?

Code Contributions

  1. Fork the repo
  2. Create a branch from main: 
    git checkout -b feature/your-feature-name
  3. Make your changes — follow existing patterns in the file you're editing
  4. Test — verify python main.py starts and your change works
  5. Commit with a clear message: 
    git commit -m "module_name: brief description of change"
  6. Push and open a Pull Request

Brain Module Contributions

If you're adding or modifying a brain module:

  • All brain modules follow a singleton pattern with get_module_name() factory function
  • State persistence via JSON files in brain/ (thread-safe with threading.RLock)
  • Every module import in agi_orchestrator.py and cognitive_integration.py is wrapped in try/except for graceful degradation
  • Modules should work independently — if your module crashes, the pipeline must continue without it
  • Include a get_stats() method for monitoring
# Standard brain module skeleton
import threading
from pathlib import Path

BRAIN_DIR = Path(__file__).parent.resolve()
STATE_FILE = BRAIN_DIR / "your_module_state.json"

class YourModule:
    def __init__(self):
        self._lock = threading.RLock()
        self._load()

    def _load(self): ...
    def _save(self): ...
    def get_stats(self) -> dict: ...

_instance = None
def get_your_module() -> YourModule:
    global _instance
    if _instance is None:
        _instance = YourModule()
    return _instance

Action Module Contributions

Actions live in actions/ and are registered in main.py:

  • Each action is a function that takes parameters and returns a result
  • Use groq_generate() or the configured LLM backend for AI-powered actions
  • Handle errors gracefully — return error strings, don't crash
  • Register in the tool definitions dict in main.py

Code Style

  • Python 3.12+ — use modern syntax (f-strings, type hints, walrus operator where clear)
  • Follow existing patterns — match the style of the file you're editing
  • Docstrings on public classes and methods (brief, not essays)
  • One job per function — if a function does two things, split it
  • No hardcoded secrets — API keys go in config/api_keys.json, never in source
  • Thread safety — brain modules use threading.RLock for state access
  • Graceful degradation — wrap external dependencies in try/except

Project Structure

Directory Purpose Key Files
brain/ 40+ cognitive modules cognitive_integration.py, agi_orchestrator.py, code_reasoning_engine.py
actions/ 56 tool actions code_helper.py, browser_control.py, security_tools.py
skills/ Skill engine + definitions cognitive_gating.py, research_agent.py, creative_studio.py
cyber/ Security pipeline mythos_pipeline.py, pipeline.py, target_guard.py
agent/ Task execution executor.py, planner.py, task_queue.py
agents/ Expert agent personas 30 specialized agents (markdown files)
security/ Permission & audit tools_guard.py, permission_manager.py
config/ Configuration api_keys.json
memory/ Memory management memory_manager.py, config_manager.py
benchmarks/ Evaluation scripts agi_benchmark_v2.py

Testing

# Start FRIDAY and verify your change works
python main.py

# Run benchmark suite
python run_arc.py --max_tasks 10
python run_gsm8k.py --max_tasks 10
python run_mmlu.py --max_tasks 10

Security

  • Never commit API keys, tokens, or credentials
  • Security tool contributions must include the authorization confirmation protocol
  • All cybersecurity features require explicit user consent before execution
  • See LEGAL.md for the full security policy and legal disclaimers

Questions?

Open an issue or reach out at subhansh.dev@gmail.com.

95K lines. 40+ modules. One teenager. Every contribution matters.