# 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
Raw data
{
"_id": null,
"home_page": null,
"name": "alloy-lang",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "agents, ai, interpreter, programming-language",
"author": "Alloy Team",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/0b/2b/153b87637f0708fe93eabb546c742aeeb1afa734df321593be5003cf1bb6/alloy_lang-0.1.0.tar.gz",
"platform": null,
"description": "# Alloy Programming Language\n\nA general-purpose programming language designed specifically for AI agents, with first-class support for agent interactions, tool definitions, and hybrid human-AI development workflows.\n\n## Overview\n\nAlloy 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.\n\n### Key Features\n\n- **Agent-First Design**: Optimized for AI agents to read, write, and maintain code\n- **Natural Language Patterns**: Syntax follows natural language conventions\n- **Complete Programming Language**: Full support for variables, tools, control flow, and data structures\n- **AI as Infrastructure**: AI models treated as computational primitives\n- **Tool Definition**: Define reusable functions with clear parameter and return specifications\n- **Multi-Agent Collaboration**: Built-in support for multiple AI agents working together\n- **Robust Error Handling**: Comprehensive error handling patterns built into the language\n\n## Quick Start\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/alloy-lang/alloy.git\ncd alloy\n\n# Install dependencies\npip install -r requirements.txt\n\n# Or install in development mode\npip install -e .[dev]\n```\n\n### Basic Usage\n\n```python\nfrom alloy import Interpreter, Parser\n\n# Create interpreter\ninterpreter = Interpreter()\nparser = Parser()\n\n# Example Alloy code\ncode = '''\n# Define a tool (function)\ntool add_numbers takes a, b returns sum {\n sum = a + b\n return sum\n}\n\n# Use the tool\nresult = add_numbers(5, 3)\n\n# Define an AI agent\nclaude = agent \"gpt-4o-mini\"\n\n# Use the agent\nanalysis, error = claude \"Analyze this data: [1, 2, 3, 4, 5]\"\n'''\n\n# Parse and execute\nast = parser.parse(code)\ninterpreter.interpret(ast)\n```\n\n### Environment Setup\n\nCreate a `.env` file in your project root:\n\n```bash\nOPENAI_API_KEY=your_openai_api_key_here\n```\n\n## Language Examples\n\n### Tool Definition and Usage\n\n```alloy\ntool calculate_average takes numbers returns average {\n sum = 0\n count = 0\n \n for num in numbers do {\n sum = sum + num\n count = count + 1\n }\n \n average = sum / count\n return average\n}\n\ndata = [10, 20, 30, 40, 50]\navg = calculate_average(data)\n```\n\n### Agent Interactions\n\n```alloy\n# Define agents with specific capabilities\nanalyst = agent \"gpt-4o-mini\" with tools data_analysis, chart_creation\nwriter = agent \"gpt-4o-mini\" with tools document_writing\n\n# Use agents for specific tasks\ninsights, error = analyst Analyze sales_data\nreport, error = writer \"Write a summary report\" insights\n```\n\n### Control Flow\n\n```alloy\n# Conditional logic\nwhen score > 90 then {\n grade = \"A\"\n} otherwise {\n grade = \"B\"\n}\n\n# Loops\nfor item in shopping_list do {\n total_cost = total_cost + item.price\n}\n\n# While loops\nwhile queue_not_empty do {\n process_next_item()\n}\n```\n\n## Project Structure\n\n```\nalloy/\n\u251c\u2500\u2500 README.md # This file\n\u251c\u2500\u2500 pyproject.toml # Python packaging configuration\n\u251c\u2500\u2500 requirements.txt # Runtime dependencies\n\u251c\u2500\u2500 .gitignore # Git ignore patterns\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 alloy/\n\u2502 \u251c\u2500\u2500 __init__.py # Package initialization\n\u2502 \u251c\u2500\u2500 lexer.py # Tokenization and lexical analysis\n\u2502 \u251c\u2500\u2500 parser.py # Grammar parsing and AST generation\n\u2502 \u251c\u2500\u2500 interpreter.py # AST execution engine\n\u2502 \u251c\u2500\u2500 ast_nodes.py # AST node type definitions\n\u2502 \u2514\u2500\u2500 environment.py # Variable and scope management\n\u251c\u2500\u2500 tests/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 test_lexer.py # Lexer tests\n\u2502 \u251c\u2500\u2500 test_parser.py # Parser tests\n\u2502 \u251c\u2500\u2500 test_interpreter.py # Interpreter tests\n\u2502 \u251c\u2500\u2500 test_language_features.py # End-to-end language tests\n\u2502 \u2514\u2500\u2500 test_examples.py # Example program tests\n\u251c\u2500\u2500 docs/\n\u2502 \u251c\u2500\u2500 language-specification.md # Complete language specification\n\u2502 \u251c\u2500\u2500 alloy-mvp-spec.md # MVP specification\n\u2502 \u2514\u2500\u2500 development.md # Development guide\n\u2514\u2500\u2500 examples/\n \u251c\u2500\u2500 basic.alloy # Basic language examples\n \u251c\u2500\u2500 agent_examples.alloy # Agent usage examples\n \u2514\u2500\u2500 tools_examples.alloy # Tool definition examples\n```\n\n## Development\n\n### Setting up for Development\n\n```bash\n# Install development dependencies\npip install -e .[dev]\n\n# Run tests\npytest\n\n# Run tests with coverage\npytest --cov=src/alloy --cov-report=html\n\n# Format code\nblack src/ tests/\n\n# Sort imports\nisort src/ tests/\n\n# Type checking\nmypy src/\n\n# Linting\nflake8 src/ tests/\n```\n\n### Test-Driven Development (TDD)\n\nThis project follows TDD practices:\n\n1. **Write tests first** for new language features\n2. **Run tests** to ensure they fail initially\n3. **Implement the minimal code** to make tests pass\n4. **Refactor** while keeping tests green\n5. **Repeat** for each new feature\n\n### Adding New Language Features\n\n1. Create tests in the appropriate `tests/test_*.py` file\n2. Update the lexer in `src/alloy/lexer.py` if new tokens are needed\n3. Update the parser in `src/alloy/parser.py` for new grammar rules\n4. Update the interpreter in `src/alloy/interpreter.py` for execution logic\n5. Add AST nodes in `src/alloy/ast_nodes.py` if needed\n6. Update documentation\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes following TDD practices\n4. Ensure all tests pass (`pytest`)\n5. Ensure code formatting is correct (`black . && isort .`)\n6. Commit your changes (`git commit -m 'Add amazing feature'`)\n7. Push to the branch (`git push origin feature/amazing-feature`)\n8. Open a Pull Request\n\n## Documentation\n\n- [Language Specification](docs/language-specification.md) - Complete language reference\n- [MVP Specification](docs/alloy-mvp-spec.md) - Minimum viable product specification\n- [Development Guide](docs/development.md) - Detailed development instructions\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Built with [PLY (Python Lex-Yacc)](https://github.com/dabeaz/ply) for lexing and parsing\n- Inspired by modern programming languages and AI-first development practices\n- Designed for the age of AI agents and human-AI collaboration",
"bugtrack_url": null,
"license": null,
"summary": "A general-purpose programming language designed for AI agents",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://alloy-lang.readthedocs.io/",
"Homepage": "https://github.com/alloy-lang/alloy",
"Issues": "https://github.com/alloy-lang/alloy/issues",
"Repository": "https://github.com/alloy-lang/alloy.git"
},
"split_keywords": [
"agents",
" ai",
" interpreter",
" programming-language"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "533a0623458ffb4487d53fcd33c90fdd0b10b8dc6946b03bb4374b98283c03d4",
"md5": "be363a5f684e7c6f6c6631da62f9093e",
"sha256": "39bc652a0ff3229f833ac7ea286b313f297604d6221423fdd0ee1b04effd1ead"
},
"downloads": -1,
"filename": "alloy_lang-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "be363a5f684e7c6f6c6631da62f9093e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 36250,
"upload_time": "2025-07-19T22:33:12",
"upload_time_iso_8601": "2025-07-19T22:33:12.108049Z",
"url": "https://files.pythonhosted.org/packages/53/3a/0623458ffb4487d53fcd33c90fdd0b10b8dc6946b03bb4374b98283c03d4/alloy_lang-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0b2b153b87637f0708fe93eabb546c742aeeb1afa734df321593be5003cf1bb6",
"md5": "ece2edc4a81f5d5b70e23baab5b352e2",
"sha256": "a4c64e3d9f0b017645bef7c272dc28c5926883e7097fbba6e9a0a8dbd7c87216"
},
"downloads": -1,
"filename": "alloy_lang-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "ece2edc4a81f5d5b70e23baab5b352e2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 135821,
"upload_time": "2025-07-19T22:33:13",
"upload_time_iso_8601": "2025-07-19T22:33:13.727546Z",
"url": "https://files.pythonhosted.org/packages/0b/2b/153b87637f0708fe93eabb546c742aeeb1afa734df321593be5003cf1bb6/alloy_lang-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-19 22:33:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alloy-lang",
"github_project": "alloy",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "alloy-lang"
}
JSON
