# 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

```bash
# 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

```python
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:

```bash
OPENAI_API_KEY=your_openai_api_key_here
```

## Language Examples

### Tool Definition and Usage

```alloy
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

```alloy
# 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

```alloy
# 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

```bash
# 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](docs/language-specification.md) - Complete language reference
- [MVP Specification](docs/alloy-mvp-spec.md) - Minimum viable product specification
- [Development Guide](docs/development.md) - Detailed development instructions

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Built with [PLY (Python Lex-Yacc)](https://github.com/dabeaz/ply) 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