{"id":17435580,"url":"https://github.com/haha-systems/silk","last_synced_at":"2026-01-31T02:31:24.091Z","repository":{"id":257987945,"uuid":"873166173","full_name":"haha-systems/silk","owner":"haha-systems","description":"Silk is an AI-native programming language that lets developers focus on intent while it handles implementation. ","archived":false,"fork":false,"pushed_at":"2024-10-15T22:01:21.000Z","size":21,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-07T03:07:59.672Z","etag":null,"topics":["ai","ai-native","ast","claude","go","golang","gpt","language","meta-language","silk"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/haha-systems.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-15T17:55:41.000Z","updated_at":"2024-11-12T18:53:32.000Z","dependencies_parsed_at":"2024-10-18T02:36:45.429Z","dependency_job_id":null,"html_url":"https://github.com/haha-systems/silk","commit_stats":null,"previous_names":["haha-systems/silk"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haha-systems%2Fsilk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haha-systems%2Fsilk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haha-systems%2Fsilk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haha-systems%2Fsilk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/haha-systems","download_url":"https://codeload.github.com/haha-systems/silk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":236745700,"owners_count":19198062,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-native","ast","claude","go","golang","gpt","language","meta-language","silk"],"created_at":"2024-10-17T10:00:44.112Z","updated_at":"2026-01-31T02:31:24.083Z","avatar_url":"https://github.com/haha-systems.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Silk\n\nA high-performance domain-specific language (DSL) for building distributed multi-agent systems using the contract-net auction protocol.\n\n## Overview\n\nSilk is a specialized programming language designed for implementing intelligent agents that coordinate through auctions and message passing. Built with Zig for performance and type safety, Silk provides first-class support for agent capabilities, policies, actions, and the contract-net protocol.\n\n### Key Features\n\n- **Agent-First Design**: Built-in constructs for capabilities, state, policies, and actions\n- **Contract-Net Protocol**: Native support for auction-based task allocation and coordination\n- **Type-Safe**: Strong typing with inference for reliability and performance\n- **High Performance**: Built with Zig, no garbage collection overhead\n- **Message Passing**: Integrated support for ZeroMQ and other transport protocols\n- **Policy/Action Separation**: Clean separation between decision-making and execution\n- **Observability**: Enterprise-grade tracing and logging support\n- **Arena Allocation**: Efficient memory management for agent runtime\n\n## Quick Start\n\n### Prerequisites\n\n- [Zig](https://ziglang.org/) 0.15.2 or higher\n- [mise](https://mise.jdx.dev/) (optional, for version management)\n\n### Installation\n\n1. Clone the repository:\n```bash\ngit clone \u003crepository-url\u003e\ncd silk\n```\n\n2. Build the project:\n```bash\nzig build\n```\n\n3. Run tests to verify installation:\n```bash\nzig build test\n```\n\n### Your First Silk Agent\n\nCreate a simple agent that responds to messages:\n\n```silk\n// Define agent capabilities\ncapability \"example.responder\" {\n  topics   = [\"tasks.simple\"]\n  latency  \u003c= 1000ms\n  quality  \u003e= 0.8\n  tools    = [\"zmq\"]\n}\n\n// Agent state\nstate message_count = 0\n\n// Initialize the agent\nhandle initialize(ctx) {\n  zmq.log(\"info\", \"Agent initialized\", {agent_id: ctx.agent_id})\n}\n\n// Handle incoming messages\nhandle process_message(msg) {\n  message_count = message_count + 1\n\n  zmq.log(\"info\", \"Processing message\", {\n    count: message_count,\n    content: msg.content\n  })\n\n  return {\n    status: \"success\",\n    processed: message_count\n  }\n}\n\n// Policy for deciding whether to bid on tasks\npolicy should_bid(stimulus) {\n  // Bid if we have capacity and the task matches our capabilities\n  if message_count \u003c 100 {\n    return {\n      bid: true,\n      confidence: 0.9,\n      estimated_cost: 50ms\n    }\n  } else {\n    return {bid: false}\n  }\n}\n\n// Action to execute when assigned a task\nact execute_task(task) {\n  let result = process_task(task)\n  yield result\n}\n\n// Learn from task outcomes\nlearn update_model(outcome) {\n  if outcome.success {\n    // Increase confidence for similar tasks\n    zmq.log(\"info\", \"Task successful, updating model\")\n  }\n}\n```\n\nRun your agent:\n```bash\nzig build run -- agents/your_agent.silk\n```\n\n### Contract-Net runtime (in-process)\n\nSilk ships an in-process Contract-Net runtime for fast local experimentation:\n- Builtins: `contract_net.announce`, `submit_bid`, `close`, `assign`, `complete`, `stats`, `on_assignment`, `on_complete`.\n- Weighting: pass `{confidence_weight: 0.6, price_weight: 0.4}` as the third arg to `announce`.\n- Example: run the leader/worker sample `zig build run -- run agents/cnp_leader.silk` to see announce → bid → close → assign → complete with callback logs.\n- The `close` result includes `winner`, `bid_count`, `confidence`, `score`, and `auction_id`; each bid is kept for debugging.\n- A tiny in-process pub/sub mock (`InprocZmq`) is available for transport testing while a real ZeroMQ adapter is designed.\n\n### Distributed transport (ZMQ preview)\n\n- Run any Silk file with dispatch enabled via `silk run \u003cfile.silk\u003e --dispatch` (inproc transport).\n- To target ZeroMQ PUB/SUB instead, add `--transport=zmq --endpoint=tcp://127.0.0.1:5555 --subscribe=cnp.` and publish/subscribe with your own processes.\n- Tune receive timeout with `--recv-timeout-ms=\u003cn\u003e`; defaults to 10ms. Heartbeat liveness window is configurable via `--heartbeat-timeout-ms=\u003cn\u003e` (default 5s).\n- Set an explicit agent id with `--agent-id=\u003cid\u003e` (defaults to a UUID) and write dispatcher JSONL logs with `--dispatch-log=cnp.log` (falls back to stdout).\n- Dispatcher enforces basic CNP envelopes (`msg_id`, `auction_id`, `sender_id`, `payload` object), drops messages past their `deadline_ms`, and ignores senders whose last heartbeat (topic `cnp.heartbeat`, optional top-level `ts`) is older than the configured timeout.\n\n### Interactive REPL\n\nSilk includes a powerful interactive REPL with enhanced error reporting, command history, and introspection capabilities:\n\n```bash\nsilk  # Start the REPL\n```\n\n#### REPL Features\n\n**Enhanced Error Reporting:**\n- Color-coded error messages (red for errors, yellow for warnings, green for success)\n- Source code snippets with error location markers (`^^^`)\n- \"Did you mean?\" suggestions for undefined variables\n- Stack traces for runtime errors\n\n**Command History:**\n- Persistent history saved to `~/.silk_history`\n- Navigate with ↑/↓ arrow keys\n- Ctrl+R for reverse search (planned)\n\n**Introspection Commands:**\n- `:symbols` - List all defined variables and functions\n- `:type \u003cexpr\u003e` - Show the type of an expression\n- `:imports` - Display loaded modules\n- `:load \u003cfile\u003e` - Load and execute a Silk file\n- `:reset` - Clear interpreter state\n- `:help` - Show available commands\n- `:clear` - Clear the screen\n- `:exit/:quit` - Exit the REPL\n\n#### Example REPL Session\n\n```silk\nSilk REPL v0.1.0\nType :help for help, :exit to quit\n\n\u003e\u003e\u003e state x = 42\n\u003e\u003e\u003e fn greet(name) {\n...   return \"Hello, \" + name\n... }\n\u003e\u003e\u003e greet(\"World\")\n\"Hello, World\"\n\u003e\u003e\u003e :symbols\nDefined symbols:\n  x: 42\n  greet: \u003cfunction\u003e\n\u003e\u003e\u003e :type x\nType: int\n\u003e\u003e\u003e :load examples/utils.silk\ninfo: Loaded file 'examples/utils.silk' successfully\n\u003e\u003e\u003e :imports\nLoaded modules:\n  examples/utils.silk\n\u003e\u003e\u003e\n```\n\n## Language Features\n\n### Core Constructs\n\n- **Declarations**: `capability`, `tool`, `state`, `policy`, `act`, `handle`, `learn`, `import`\n- **Statements**: `let`, `return`, `yield`, `if`/`then`/`else`, `for`, `while`\n- **Types**: `int`, `float`, `string`, `bool`, `duration`, arrays, objects, `Result\u003cT\u003e`, `Bid`, `Stimulus`\n- **Built-in Functions**: Message passing, timers, logging, and more\n\n### Agent Components\n\n1. **Capability Declarations**: Define what your agent can do and its constraints\n2. **State Management**: Persistent and ephemeral state with automatic management\n3. **Policy Functions**: Decision-making logic for bidding and task selection\n4. **Action Functions**: Execution logic for performing tasks\n5. **Message Handlers**: Process incoming messages and events\n6. **Learning Functions**: Adapt based on outcomes and feedback\n\n### Contract-Net Protocol\n\nSilk provides native support for the contract-net auction protocol:\n\n```silk\n// Auction leader announces task\nannounce_task(task_spec) -\u003e List\u003cBid\u003e\n\n// Agents submit bids\npolicy calculate_bid(task) -\u003e Bid\n\n// Leader assigns task to winner\nassign_task(agent_id, task) -\u003e Assignment\n\n// Agent executes and returns result\nact perform_task(assignment) -\u003e Result\n```\n\nSee the [example leader agent](agents/leader.silk) for a complete auction orchestration implementation.\n\n## Project Structure\n\n```\nsilk/\n├── src/                      # Core language implementation\n│   ├── Lexer.zig            # Tokenization and lexical analysis\n│   ├── Token.zig            # Token type definitions\n│   ├── Parser.zig           # Recursive descent parser with Pratt parsing\n│   ├── Ast.zig              # Abstract Syntax Tree definitions\n│   ├── Value.zig            # Runtime value types and environment\n│   ├── Interpreter.zig      # Tree-walking interpreter\n│   ├── main.zig             # CLI entry point\n│   └── root.zig             # Public module API\n├── agents/                   # Example agent implementations\n│   └── leader.silk          # Contract-net auction leader example\n├── docs/                     # Documentation\n│   └── SILK_REFERENCE.md    # Complete language reference\n├── build.zig                # Build configuration\n├── build.zig.zon            # Package manifest\n└── README.md                # This file\n```\n\n## Development\n\n### Building\n\n```bash\n# Build executable and library\nzig build\n\n# Build with optimizations\nzig build -Doptimize=ReleaseFast\n\n# Install to system (optional)\nzig build install\n```\n\n### Running\n\n```bash\n# Run the Silk CLI\nzig build run\n\n# Run with an agent file\nzig build run -- agents/leader.silk\n\n# Run with arguments\nzig build run -- --help\n```\n\n### Testing\n\nThe project includes comprehensive unit tests for all components:\n\n```bash\n# Run all tests\nzig build test\n\n# Run with verbose output\nzig build test -- --summary all\n\n# Run specific test\nzig build test -- --test-filter \"parser\"\n```\n\n**Test Coverage**:\n- Lexer: Token generation, string/number parsing, comments, duration literals\n- Parser: All declaration types, statements, expressions, precedence rules\n- Interpreter: Expression evaluation, control flow, function calls, state management\n\n### Code Organization\n\nThe implementation follows a clean pipeline architecture:\n\n1. **Lexer** (552 lines): Source code → Tokens\n2. **Parser** (1,176 lines): Tokens → Abstract Syntax Tree (AST)\n3. **Interpreter** (704 lines): AST → Runtime execution\n\nEach component is:\n- Self-contained with minimal dependencies\n- Thoroughly tested with unit tests\n- Documented with inline comments\n- Memory-safe using Zig's arena allocators\n\n## Documentation\n\n- **[Language Reference](docs/SILK_REFERENCE.md)**: Complete language specification, syntax, and semantics\n- **[Example Agents](agents/)**: Real-world agent implementations\n- **API Documentation**: Generate with `zig build docs` (coming soon)\n\n## Using Silk as a Library\n\nSilk can be used as a library in your Zig projects:\n\n```zig\nconst silk = @import(\"silk\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    defer _ = gpa.deinit();\n    const allocator = gpa.allocator();\n\n    // Parse Silk source code\n    const source = \"state counter = 0\";\n    var lexer = silk.Lexer.init(source);\n    var parser = try silk.Parser.init(allocator, \u0026lexer);\n    defer parser.deinit();\n\n    var program = try parser.parseProgram();\n\n    // Execute the program\n    var interpreter = try silk.Interpreter.init(allocator);\n    defer interpreter.deinit();\n\n    try interpreter.execute(\u0026program);\n}\n```\n\nAdd to your `build.zig.zon`:\n```zig\n.dependencies = .{\n    .silk = .{\n        .url = \"https://github.com/your-org/silk/archive/\u003ccommit\u003e.tar.gz\",\n        .hash = \"\u003chash\u003e\",\n    },\n},\n```\n\n## Development Status\n\n**Version**: 0.0.0 (Early Development)\n\n### Completed\n\n- ✅ Complete lexer with comprehensive token support\n- ✅ Recursive descent parser with Pratt parsing for expressions\n- ✅ Tree-walking interpreter with arena allocation\n- ✅ Core language constructs (declarations, statements, expressions)\n- ✅ Type system foundation (primitives, arrays, objects)\n- ✅ Function definitions and calls\n- ✅ Control flow (if/else, loops)\n- ✅ Variable binding and scoping\n- ✅ Comprehensive test suite\n\n### In Progress\n\n- 🚧 Standard library implementation\n- 🚧 Built-in functions (message passing, timers, etc.)\n- 🚧 Contract-net protocol runtime\n- 🚧 Transport layer integrations (ZeroMQ, TCP, Unix sockets)\n- 🚧 Advanced language features (streams, async/await)\n\n### Planned\n\n- 📋 JIT compilation or bytecode VM for performance\n- 📋 IDE support (LSP, syntax highlighting)\n- 📋 Package manager\n- 📋 Formal specification and verification tools\n- 📋 Distributed runtime and cluster management\n- 📋 Monitoring and observability dashboard\n\n## Contributing\n\nContributions are welcome! Here's how to get started:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes with tests\n4. Ensure all tests pass (`zig build test`)\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n### Development Guidelines\n\n- Follow Zig style conventions\n- Add tests for all new features\n- Update documentation as needed\n- Keep commits focused and descriptive\n- Ensure code compiles with no warnings\n\n## Architecture\n\nSilk uses a tree-walking interpreter architecture for simplicity and clarity:\n\n```\nSource Code\n    ↓\n[Lexer] → Tokens\n    ↓\n[Parser] → Abstract Syntax Tree (AST)\n    ↓\n[Interpreter] → Runtime Execution\n    ↓\nResults\n```\n\nKey design decisions:\n\n- **Arena Allocation**: All AST nodes and runtime values use arena allocators for efficient bulk deallocation\n- **Two-phase Execution**: Parse phase (compilation) and execution phase are separate\n- **Immutable AST**: Once parsed, the AST is immutable during execution\n- **Environment Chain**: Lexical scoping via parent environment pointers\n- **Tagged Unions**: Type-safe runtime values using Zig's tagged unions\n\n## Performance\n\nWhile currently an interpreter, Silk is designed for performance:\n\n- Written in Zig (no GC, predictable performance)\n- Arena allocation reduces allocation overhead\n- Zero-copy string handling where possible\n- Efficient value representation with tagged unions\n- Planned: JIT compilation and bytecode VM\n\n## Community\n\n- **Issues**: [GitHub Issues](https://github.com/your-org/silk/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/your-org/silk/discussions)\n- **Documentation**: [docs/](docs/)\n\n## Acknowledgments\n\n- Built with [Zig](https://ziglang.org/)\n- Inspired by the contract-net protocol from multi-agent systems research\n- Parser design influenced by Pratt parsing techniques\n\n## Related Projects\n\n- [ZeroMQ](https://zeromq.org/) - High-performance async messaging library\n- [Zig Language Server (ZLS)](https://github.com/zigtools/zls) - IDE support for Zig\n\n---\n\n**Note**: Silk is in early development. APIs and language features are subject to change. Feedback and contributions are greatly appreciated!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaha-systems%2Fsilk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhaha-systems%2Fsilk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaha-systems%2Fsilk/lists"}