Alloy Programming Language

A general-purpose programming language designed specifically for AI agents, with first-class support for agent interactions, tool definitions, and hybrid human-AI development workflows.

Overview

Alloy is a complete programming language that treats artificial intelligence as a first-class citizen alongside traditional deterministic computation. The language provides all the capabilities of modern programming languages - variables, functions (tools), control flow, data structures, and error handling - with AI integration seamlessly woven into the fabric of the language.

Key Features

• Agent-First Design: Optimized for AI agents to read, write, and maintain code
• Natural Language Patterns: Syntax follows natural language conventions
• Complete Programming Language: Full support for variables, tools, control flow, and data structures
• AI as Infrastructure: AI models treated as computational primitives
• Tool Definition: Define reusable functions with clear parameter and return specifications
• Multi-Agent Collaboration: Built-in support for multiple AI agents working together
• Robust Error Handling: Comprehensive error handling patterns built into the language

Quick Start

Installation

# Clone the repository
git clone https://github.com/alloy-lang/alloy.git
cd alloy

# Install dependencies
pip install -r requirements.txt

# Or install in development mode
pip install -e .[dev]

Basic Usage

from alloy import Interpreter, Parser

# Create interpreter
interpreter = Interpreter()
parser = Parser()

# Example Alloy code
code = '''
# Define a tool (function)
tool add_numbers takes a, b returns sum {
    sum = a + b
    return sum
}

# Use the tool
result = add_numbers(5, 3)

# Define an AI agent
claude = agent "gpt-4o-mini"

# Use the agent
analysis, error = claude "Analyze this data: [1, 2, 3, 4, 5]"
'''

# Parse and execute
ast = parser.parse(code)
interpreter.interpret(ast)

Environment Setup

Create a .env file in your project root:

OPENAI_API_KEY=your_openai_api_key_here

Language Examples

Tool Definition and Usage

tool calculate_average takes numbers returns average {
    sum = 0
    count = 0
    
    for num in numbers do {
        sum = sum + num
        count = count + 1
    }
    
    average = sum / count
    return average
}

data = [10, 20, 30, 40, 50]
avg = calculate_average(data)

Agent Interactions

# Define agents with specific capabilities
analyst = agent "gpt-4o-mini" with tools data_analysis, chart_creation
writer = agent "gpt-4o-mini" with tools document_writing

# Use agents for specific tasks
insights, error = analyst Analyze sales_data
report, error = writer "Write a summary report" insights

Control Flow

# Conditional logic
when score > 90 then {
    grade = "A"
} otherwise {
    grade = "B"
}

# Loops
for item in shopping_list do {
    total_cost = total_cost + item.price
}

# While loops
while queue_not_empty do {
    process_next_item()
}

Project Structure

alloy/
├── README.md                    # This file
├── pyproject.toml              # Python packaging configuration
├── requirements.txt            # Runtime dependencies
├── .gitignore                  # Git ignore patterns
├── src/
│   └── alloy/
│       ├── __init__.py         # Package initialization
│       ├── lexer.py           # Tokenization and lexical analysis
│       ├── parser.py          # Grammar parsing and AST generation
│       ├── interpreter.py     # AST execution engine
│       ├── ast_nodes.py       # AST node type definitions
│       └── environment.py     # Variable and scope management
├── tests/
│   ├── __init__.py
│   ├── test_lexer.py         # Lexer tests
│   ├── test_parser.py        # Parser tests
│   ├── test_interpreter.py   # Interpreter tests
│   ├── test_language_features.py  # End-to-end language tests
│   └── test_examples.py      # Example program tests
├── docs/
│   ├── language-specification.md  # Complete language specification
│   ├── alloy-mvp-spec.md      # MVP specification
│   └── development.md        # Development guide
└── examples/
    ├── basic.alloy           # Basic language examples
    ├── agent_examples.alloy  # Agent usage examples
    └── tools_examples.alloy  # Tool definition examples

Development

Setting up for Development

# Install development dependencies
pip install -e .[dev]

# Run tests
pytest

# Run tests with coverage
pytest --cov=src/alloy --cov-report=html

# Format code
black src/ tests/

# Sort imports
isort src/ tests/

# Type checking
mypy src/

# Linting
flake8 src/ tests/

Test-Driven Development (TDD)

This project follows TDD practices:

1. Write tests first for new language features
2. Run tests to ensure they fail initially
3. Implement the minimal code to make tests pass
4. Refactor while keeping tests green
5. Repeat for each new feature

Adding New Language Features

1. Create tests in the appropriate tests/test_*.py file
2. Update the lexer in src/alloy/lexer.py if new tokens are needed
3. Update the parser in src/alloy/parser.py for new grammar rules
4. Update the interpreter in src/alloy/interpreter.py for execution logic
5. Add AST nodes in src/alloy/ast_nodes.py if needed
6. Update documentation

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes following TDD practices
4. Ensure all tests pass (pytest)
5. Ensure code formatting is correct (black . && isort .)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Documentation

• Language Specification - Complete language reference
• MVP Specification - Minimum viable product specification
• Development Guide - Detailed development instructions

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with PLY (Python Lex-Yacc) for lexing and parsing
• Inspired by modern programming languages and AI-first development practices
• Designed for the age of AI agents and human-AI collaboration