Contributing to AI Workforce Research Platform

Thank you for your interest in contributing to this research project! This document provides guidelines for contributing to the AI Workforce of the Future research platform.

📋 Table of Contents

Code of Conduct
Important Notice
Types of Contributions
Getting Started
Development Workflow
Code Standards
Commit Guidelines
Pull Request Process
Academic Integrity

📜 Code of Conduct

Our Pledge

We are committed to providing a welcoming and inclusive environment for all contributors. We expect all participants to:

Be respectful — Treat everyone with dignity and respect
Be constructive — Provide helpful feedback and criticism
Be collaborative — Work together towards common goals
Be professional — Maintain academic and professional standards

Unacceptable Behavior

Harassment, discrimination, or offensive comments
Publishing others' private information without permission
Plagiarism or academic dishonesty
Any conduct that violates academic integrity standards

⚠️ Important Notice

This is an academic research project developed as part of a Master's thesis at Aalto University School of Business.

Licensing Constraints

Before contributing, please understand:

All Rights Reserved — This project is proprietary software
No Redistribution — You may not distribute the code without explicit permission
No Commercial Use — The code may not be used for commercial purposes
Academic Use Only — Contributions must support academic research goals

Contribution Agreement

By submitting a contribution, you agree that:

Your contribution becomes part of the project under the same license
You grant the project author full rights to use, modify, and distribute your contribution
You have the right to submit the contribution (it's your original work or properly licensed)
Your contribution may be used in academic publications and presentations

🎯 Types of Contributions

We welcome the following types of contributions:

✅ Encouraged Contributions

Type	Description	Priority
🐛 Bug Fixes	Fix issues in existing functionality	High
📝 Documentation	Improve README, comments, or guides	High
🧪 Tests	Add or improve test coverage	Medium
🎨 UI/UX Improvements	Enhance user interface and experience	Medium
⚡ Performance	Optimize code performance	Medium
🔧 Tooling	Improve development workflow	Low

⚠️ Contributions Requiring Discussion

Please open an issue before working on:

New autonomy stages or agent types
Major architectural changes
New external service integrations
Changes to the research methodology

❌ Not Accepted

Features unrelated to research goals
Breaking changes without migration path
Code that compromises academic integrity
Proprietary third-party code without proper licensing

🚀 Getting Started

Prerequisites

Read the README.md to understand the project
Ensure you have the development environment set up
Familiarize yourself with the codebase structure

Development Environment

# Clone the repository (if you have access)
git clone <repository-url>
cd agentic_ai

# Backend setup
cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Frontend setup
cd ../frontend
npm install

# Start development servers
# See README.md for full instructions

Project Structure

agentic_ai/
├── backend/                 # FastAPI backend
│   ├── app/
│   │   ├── agents/         # Agent definitions
│   │   ├── core/           # Core services
│   │   ├── stages/         # Stage implementations
│   │   ├── tools/          # Agent tools
│   │   └── websocket/      # WebSocket handlers
│   └── requirements.txt
├── frontend/               # React + TypeScript frontend
│   ├── src/
│   │   ├── components/     # UI components
│   │   ├── pages/          # Route pages
│   │   ├── hooks/          # Custom hooks
│   │   └── stores/         # Zustand stores
│   └── package.json
├── graphiti/               # Graphiti MCP server (submodule)
│   └── mcp_server/         # MCP server implementation
└── public/                 # Static assets

💻 Development Workflow

1. Create a Branch

# For features
git checkout -b feature/your-feature-name

# For bug fixes
git checkout -b fix/issue-description

# For documentation
git checkout -b docs/what-youre-documenting

2. Make Changes

Follow the code standards below
Write meaningful commit messages
Add tests for new functionality
Update documentation as needed

3. Test Your Changes

# Backend tests
cd backend
pytest

# Frontend linting
cd frontend
npm run lint

# Build check
npm run build

4. Submit Pull Request

Push your branch
Create a pull request with clear description
Reference any related issues
Wait for review

📏 Code Standards

Python (Backend)

# Use type hints
def process_data(dataset: str, options: dict[str, Any]) -> AnalysisResult:
    """
    Process the dataset with given options.
    
    Args:
        dataset: The dataset content as string
        options: Processing options
        
    Returns:
        AnalysisResult object with processed data
    """
    pass

# Use 4-space indentation
# Maximum line length: 100 characters
# Use docstrings for public functions
# Follow PEP 8 style guide

Tools:

Formatter: black or ruff format
Linter: ruff or pylint
Type checker: pyright or mypy

TypeScript (Frontend)

// Use explicit types
interface AnalysisResult {
  id: string;
  status: 'pending' | 'complete' | 'error';
  data: Record<string, unknown>;
}

// Use functional components with typed props
interface ButtonProps {
  onClick: () => void;
  disabled?: boolean;
  children: React.ReactNode;
}

const Button: React.FC<ButtonProps> = ({ onClick, disabled, children }) => {
  return (
    <button onClick={onClick} disabled={disabled}>
      {children}
    </button>
  );
};

Tools:

Formatter: Prettier (via ESLint)
Linter: ESLint with TypeScript plugin

CSS/Tailwind

// Use Tailwind utility classes
<div className="flex items-center gap-4 p-6 bg-white/5 rounded-xl border border-white/10">
  <span className="text-sm font-medium text-slate-300">Content</span>
</div>

// Group related classes logically:
// 1. Layout (flex, grid, position)
// 2. Spacing (p, m, gap)
// 3. Sizing (w, h)
// 4. Colors (bg, text, border)
// 5. Typography (font, text)
// 6. Effects (shadow, opacity)

📝 Commit Guidelines

Commit Message Format

<type>(<scope>): <subject>

[optional body]

[optional footer]

Types

Type	Description
`feat`	New feature
`fix`	Bug fix
`docs`	Documentation changes
`style`	Code style changes (formatting, etc.)
`refactor`	Code refactoring
`test`	Adding or updating tests
`chore`	Maintenance tasks
`perf`	Performance improvements

Examples

# Good commit messages
feat(agents): add new domain expert agent
fix(websocket): resolve connection timeout issue
docs(readme): update installation instructions
refactor(stages): simplify stage registry pattern

# Bad commit messages
fixed stuff
update
WIP
asdfasdf

Commit Best Practices

Atomic commits — Each commit should be a single logical change
Present tense — "Add feature" not "Added feature"
Imperative mood — "Fix bug" not "Fixes bug"
Reference issues — Include issue numbers when applicable

🔄 Pull Request Process

Before Submitting

Code follows project style guidelines
Tests pass locally
Documentation is updated
Commit messages follow guidelines
No unnecessary files are included

PR Description Template

## Description
Brief description of the changes.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Refactoring
- [ ] Other (please describe)

## Testing
Describe how you tested your changes.

## Related Issues
Fixes #123 (if applicable)

## Screenshots
(if applicable)

## Checklist
- [ ] I have read the CONTRIBUTING.md guidelines
- [ ] My code follows the project's style
- [ ] I have added/updated tests as needed
- [ ] I have updated documentation as needed

Review Process

Automated checks — CI will run linting and tests
Code review — Maintainer will review the code
Discussion — Address any feedback or questions
Approval — Once approved, PR will be merged

🎓 Academic Integrity

This project is part of academic research. All contributors must:

Do ✅

Write original code
Properly cite external sources
Attribute ideas and implementations
Follow academic integrity guidelines
Respect intellectual property rights

Don't ❌

Copy code without attribution
Misrepresent authorship
Use proprietary code without permission
Violate any academic policies

Attribution

If you use code or ideas from external sources:

# Code adapted from: https://example.com/source
# Original author: Author Name
# License: MIT
def adapted_function():
    pass

📬 Contact

For questions about contributing:

Author: Ali Amaan
Institution: Aalto University School of Business
Programme: IDBM (International Design Business Management)

_{Thank you for contributing to AI research! 🤖}

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History