{"id":29813320,"url":"https://github.com/idyllic-labs/idyll-engine","last_synced_at":"2025-07-28T19:02:07.016Z","repository":{"id":304831939,"uuid":"1018515455","full_name":"idyllic-labs/idyll-engine","owner":"idyllic-labs","description":"A context-building execution engine for AI-native programming","archived":false,"fork":false,"pushed_at":"2025-07-27T07:53:57.000Z","size":1174,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-27T07:58:52.043Z","etag":null,"topics":["agent-framework","ai","intelligence-design","notion"],"latest_commit_sha":null,"homepage":"https://idyllic.so","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/idyllic-labs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2025-07-12T12:31:44.000Z","updated_at":"2025-07-27T07:54:01.000Z","dependencies_parsed_at":"2025-07-16T07:56:50.168Z","dependency_job_id":"d09af61b-dffe-4c2d-83c9-fdeb527699f0","html_url":"https://github.com/idyllic-labs/idyll-engine","commit_stats":null,"previous_names":["idyllic-labs/idyll-engine"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/idyllic-labs/idyll-engine","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/idyllic-labs%2Fidyll-engine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/idyllic-labs%2Fidyll-engine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/idyllic-labs%2Fidyll-engine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/idyllic-labs%2Fidyll-engine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/idyllic-labs","download_url":"https://codeload.github.com/idyllic-labs/idyll-engine/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/idyllic-labs%2Fidyll-engine/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267569126,"owners_count":24109015,"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","status":"online","status_checked_at":"2025-07-28T02:00:09.689Z","response_time":68,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["agent-framework","ai","intelligence-design","notion"],"created_at":"2025-07-28T19:00:38.885Z","updated_at":"2025-07-28T19:02:06.888Z","avatar_url":"https://github.com/idyllic-labs.png","language":"TypeScript","readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/idyllic-labs/idyll-engine/blob/main/assets/banner.png\" alt=\"Idyll Engine\" width=\"100%\" /\u003e\n\u003c/div\u003e\n\n# Idyll Engine\n\n\u003e A context-building execution engine for AI-native programming\n\n\u003cdiv align=\"center\"\u003e\n\n[![npm version](https://img.shields.io/npm/v/@idyllic-labs/idyll-engine.svg)](https://www.npmjs.com/package/@idyllic-labs/idyll-engine)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)\n[![Node](https://img.shields.io/badge/Node-18.0+-green.svg)](https://nodejs.org/)\n[![CI](https://github.com/idyllic-labs/idyll-engine/actions/workflows/ci.yml/badge.svg)](https://github.com/idyllic-labs/idyll-engine/actions/workflows/ci.yml)\n\n\u003c/div\u003e\n\nIdyll Engine reimagines programming for the AI era. Instead of functions that transform data and produce side effects, Idyll functions build context that AI interprets to determine relevance. This paradigm shift enables a new form of programming where execution is exploration and results are contextual understanding.\n\n**[Read our Manifesto →](MANIFESTO.md)**\n\n## Table of Contents\n\n- [Philosophy: Context-Driven Computation](#philosophy-context-driven-computation)\n  - [The Paradigm Shift](#the-paradigm-shift)\n  - [Homoiconicity: Code as Living Documents](#homoiconicity-code-as-living-documents)\n- [Computational Insights](#computational-insights)\n- [How This Changes AI Programming](#how-this-changes-ai-programming)\n  - [The String-Based Intelligence Model](#the-string-based-intelligence-model)\n  - [Why This Isn't Another Automation Tool](#why-this-isnt-another-automation-tool)\n- [Core Features](#core-features)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n  - [Context-Building Example](#context-building-example)\n  - [AI Agent with Custom Functions](#ai-agent-with-custom-functions)\n- [Why This Matters](#why-this-matters)\n- [Grammar and Language Design](#grammar-and-language-design)\n  - [Why XML?](#why-xml)\n  - [The Execution Layer](#the-execution-layer)\n  - [Grammar Structure (EBNF-style)](#grammar-structure-ebnf-style)\n  - [Key Grammar Insights](#key-grammar-insights)\n- [Technical Details](#technical-details)\n  - [Function Naming](#function-naming)\n- [CLI Usage](#cli-usage)\n- [API Reference](#api-reference)\n- [Examples](#examples)\n- [Development](#development)\n- [Documentation](#documentation)\n- [The Vision: Community-Driven Intelligence Construction](#the-vision-community-driven-intelligence-construction)\n- [Community](#community)\n- [License](#license)\n- [Acknowledgments](#acknowledgments)\n- [Citation](#citation)\n\n## Philosophy: Context-Driven Computation\n\nThe Idyll language fundamentally reimagines programming for the AI era. Instead of functions that transform data and produce side effects, Idyll functions **build context** that AI interprets to determine relevance.\n\n### The Paradigm Shift\n\n**Traditional Programming**: Execute → Transform → Return  \n**Idyllic Programming**: Execute → Augment Context → AI Interprets\n\nIn Idyllic, function calls don't just compute—they accumulate context. The AI model becomes the interpreter of this context, extracting what matters for the task at hand. This mirrors how human intelligence works: we gather information, build understanding, and extract meaning based on intent.\n\n### Homoiconicity: Code as Living Documents\n\nIdyllic embraces true homoiconicity—programs are documents, documents are programs. An `\u003cagent\u003e` definition isn't just configuration, it's executable context. Custom functions aren't subroutines, they're documented patterns of context accumulation. The XML structure is both human-readable documentation and machine-executable code.\n\n## Computational Insights\n\n### 1. **Context Accumulation Over Direct Returns**\nFunctions contribute to an ever-growing context rather than producing isolated results. Each function call enriches the computational environment.\n\n### 2. **Linear Execution as Feature**\nNo recursion, no complex control flow—just sequential context building. This maps perfectly to how transformer models process information.\n\n### 3. **Variables as Context Queries**\nVariables aren't memory locations but prompts for context-aware resolution. `\u003cvariable name=\"topic\" prompt=\"What to search for\" /\u003e` asks the AI to resolve based on accumulated context.\n\n### 4. **Response Pipeline as Intelligence Layer**\nThe middleware system acts as a compression layer, distilling verbose execution results into what the AI actually needs—solving the context window problem elegantly.\n\n## How This Changes AI Programming\n\n### From Tools to Context Providers\nTraditional: \"Call function X to get result Y\"  \nIdyllic: \"Call function X to add context, let AI determine relevance\"\n\n### From State to Flow\nTraditional: Manage state across function calls  \nIdyllic: State IS the accumulated context flow\n\n### From Explicit to Emergent\nTraditional: Explicitly handle every case  \nIdyllic: Patterns emerge from context interpretation\n\n### From Imperative to Declarative Intent\nTraditional: \"How to compute\"  \nIdyllic: \"What context to build\"\n\n### The String-Based Intelligence Model\n\nJust as humans resolve everything into the visual domain in working memory, Idyllic resolves all values into rich, composable strings with references and pointers. The context becomes the working memory.\n\n#### Augmented Strings: Beyond Plain Text\n\nOur strings aren't just text - they're **augmented with semantic markers**:\n\n```xml\n\u003ccontent\u003e\n  Analyze \u003cmention:document id=\"doc123\"\u003ethe architecture doc\u003c/mention:document\u003e\n  and compare with \u003cmention:user id=\"usr456\"\u003eJohn's\u003c/mention:user\u003e proposal\n  focusing on \u003cvariable name=\"aspect\" prompt=\"What aspect to analyze\"/\u003e \n  \u003cannotation confidence=\"0.8\"\u003eThis seems related to last week's discussion\u003c/annotation\u003e\n\u003c/content\u003e\n```\n\nThese augmentations create a **rich semantic graph** within the text:\n- **Mentions** create explicit references to entities (documents, users, agents)\n- **Variables** are prompts for contextual resolution, not static values\n- **Annotations** add metadata and confidence layers\n- **Links** preserve external references while maintaining readability\n\n#### The Execution Engine: Context-Driven Semantics\n\nWe layer a lightweight execution engine on top of XML that adds **context-driven semantics**:\n\n1. **Sequential Context Building** - Each function call adds to accumulated context\n2. **Variable Resolution** - AI resolves variables based on accumulated context, not static scope\n3. **Error Resilience** - Failed functions still contribute partial context\n4. **Semantic Preservation** - The meaning is in the text + augmentations, not in types\n\n#### Combinators for Intelligence\n\nThe real power comes from **functional combinators** that work with context:\n\n```xml\n\u003c!-- Combinator: Sequential exploration --\u003e\n\u003cfunction title=\"Deep Analysis\"\u003e\n  \u003cfncall fn=\"explore:surface\"\u003eInitial exploration\u003c/fncall\u003e\n  \u003cfncall fn=\"explore:patterns\"\u003eFind patterns in previous context\u003c/fncall\u003e\n  \u003cfncall fn=\"explore:anomalies\"\u003eWhat doesn't fit the patterns?\u003c/fncall\u003e\n\u003c/function\u003e\n\n\u003c!-- Combinator: Parallel perspectives --\u003e\n\u003cfunction title=\"Multi-Perspective Analysis\"\u003e\n  \u003cfncall fn=\"analyze:technical\"\u003eTechnical implications\u003c/fncall\u003e\n  \u003cfncall fn=\"analyze:business\"\u003eBusiness impact\u003c/fncall\u003e\n  \u003cfncall fn=\"analyze:user\"\u003eUser experience angle\u003c/fncall\u003e\n  \u003cfncall fn=\"synthesize:perspectives\"\u003eCombine all viewpoints\u003c/fncall\u003e\n\u003c/function\u003e\n```\n\nThese aren't traditional function compositions - they're **context combinators** that build understanding.\n\nThis design choice is fundamental:\n- **Variables in natural language** rather than rigid JSON schemas\n- **Intent expression** through string interpolation: `\"Find breakthroughs in \u003cvariable name='field'/\u003e\"`\n- **Context accumulation** means programs move forward even through errors\n- **Non-brittle by design** - unlike automation tools, this is an experimental programming paradigm\n\nWe deliberately chose expressiveness over efficiency. JSON schemas are faster but they cage intelligence. String interpolation with variables lets you experiment with AI capabilities at the speed of thought. You can always optimize later once patterns emerge.\n\n### Why This Isn't Another Automation Tool\n\nTraditional automation breaks at the first unexpected input. Idyllic embraces the messiness of intelligence:\n- Functions that error still contribute context\n- Partial results are valid results \n- The AI interprets accumulated context to recover and continue\n- Each execution teaches you something about the problem space\n\nThis isn't about building reliable workflows - it's about **constructing intelligence** through experimentation.\n\n## Core Features\n\n- **Context-Building Functions**: Functions accumulate context rather than just returning values\n- **Homoiconic Documents**: XML documents that are simultaneously code, data, and documentation\n- **AI-Native Variables**: Variables resolved through context interpretation, not memory lookup\n- **Response Pipeline**: Intelligent middleware that compresses execution context for AI consumption\n- **Linear Execution Model**: Sequential context accumulation perfectly aligned with transformer architectures\n- **Custom Functions**: Reusable patterns of context accumulation, not traditional subroutines\n- **Instrumentation Hooks**: Complete observability into context building with timing and result tracking\n\n## Installation\n\n```bash\n# npm\nnpm install @idyllic-labs/idyll-engine\n\n# yarn\nyarn add @idyllic-labs/idyll-engine\n\n# pnpm\npnpm add @idyllic-labs/idyll-engine\n\n# bun\nbun add @idyllic-labs/idyll-engine\n```\n\n## Quick Start\n\n### Context-Building Example\n\n```typescript\nimport { parseXmlToAst, DocumentExecutor, createFunctionRegistry, defineFunction } from '@idyllic-labs/idyll-engine';\n\n// Functions that build context, not just transform data\nconst functions = createFunctionRegistry({\n  'search:web': defineFunction({\n    schema: z.object({ query: z.string() }),\n    description: 'Add search results to context',\n    execute: async (params, content, context) =\u003e ({\n      results: ['result1', 'result2'],\n      searchedFor: params.query,\n      // This becomes part of the accumulated context\n    }),\n  }),\n  'ai:summarize': defineFunction({\n    schema: z.object({ style: z.string() }),\n    description: 'Summarize accumulated context',\n    execute: async (params, content, context) =\u003e ({\n      // Access previous results from context\n      summary: `Summarized ${context.previousResults.size} previous operations`,\n      basedOn: Array.from(context.previousResults.keys()),\n    }),\n  }),\n});\n\n// Documents are programs - homoiconicity in action\nconst document = parseXmlToAst(`\n  \u003cdocument\u003e\n    \u003cp\u003eResearch Task\u003c/p\u003e\n    \u003cfncall idyll-fn=\"search:web\"\u003e\n      \u003cparams\u003e{\"query\": \"AI breakthroughs\"}\u003c/params\u003e\n      \u003ccontent\u003eSearch for latest developments\u003c/content\u003e\n    \u003c/fncall\u003e\n    \u003cfncall idyll-fn=\"ai:summarize\"\u003e\n      \u003cparams\u003e{\"style\": \"bullet-points\"}\u003c/params\u003e\n      \u003ccontent\u003eSummarize the findings\u003c/content\u003e\n    \u003c/fncall\u003e\n  \u003c/document\u003e\n`);\n\n// Execute with instrumentation to observe context building\nconst executor = new DocumentExecutor({ \n  functions,\n  hooks: {\n    afterExecution: (fn, result, duration) =\u003e {\n      console.log(`Context augmented by ${fn} in ${duration}ms`);\n    }\n  }\n});\nconst report = await executor.execute({ \n  mode: 'document',\n  document,\n  options: { functions }\n});\n```\n\n### AI Agent with Custom Functions\n\n```typescript\nimport { Agent, parseXmlToAst } from '@idyllic-labs/idyll-engine';\n\n// Agents are documents - code and documentation unified\nconst agentProgram = parseXmlToAst(`\n  \u003cagent name=\"Research Assistant\"\u003e\n    \u003cp\u003eI help with research by building context through function calls.\u003c/p\u003e\n    \n    \u003c!-- Custom function: a reusable pattern of context accumulation --\u003e\n    \u003cfunction title=\"Deep Research\" icon=\"🔬\"\u003e\n      \u003cfunction:definition\u003e\n        \u003cfncall idyll-fn=\"search:web\"\u003e\n          \u003cparams\u003e{\"maxResults\": 10}\u003c/params\u003e\n          \u003ccontent\u003eSearch for \u003cvariable name=\"topic\" prompt=\"Research topic\" /\u003e\u003c/content\u003e\n        \u003c/fncall\u003e\n        \u003cfncall idyll-fn=\"analyze:relevance\"\u003e\n          \u003cparams\u003e{}\u003c/params\u003e\n          \u003ccontent\u003eFilter for \u003cvariable name=\"criteria\" prompt=\"Relevance criteria\" /\u003e\u003c/content\u003e\n        \u003c/fncall\u003e\n        \u003cfncall idyll-fn=\"format:report\"\u003e\n          \u003cparams\u003e{}\u003c/params\u003e\n          \u003ccontent\u003eFormat findings\u003c/content\u003e\n        \u003c/fncall\u003e\n      \u003c/function:definition\u003e\n    \u003c/function\u003e\n  \u003c/agent\u003e\n`);\n\n// The agent interprets accumulated context\nconst agent = new Agent({\n  program: agentProgram,\n  model: aiModel,\n  functions: contextBuildingFunctions,\n  responseMiddleware: [\n    // Compress verbose context into what matters\n    contextCompressionMiddleware\n  ]\n});\n\n// Variables are resolved through context, not assignment\nconst result = await agent.chat([\n  { role: 'user', content: 'Research quantum computing breakthroughs' }\n]);\n```\n\n## Why This Matters\n\nIdyllic represents a fundamental shift in how we think about programming in the AI era. By treating computation as context accumulation rather than data transformation, we align programming with how AI models naturally process information. \n\nThe homoiconic nature means every program is simultaneously:\n- **Executable code** that builds context\n- **Living documentation** that explains intent  \n- **AI-readable structure** that guides interpretation\n\nThis isn't just a new syntax—it's a new computational philosophy where meaning emerges from context, intelligence interprets accumulation, and programming becomes a conversation between human intent and AI understanding.\n\n## Grammar and Language Design\n\n### Why XML?\n\nThe choice of XML is deliberate and strategic:\n\n1. **Ease of Parsing** - Well-established parsers, no ambiguity in structure\n2. **Tooling Ecosystem** - XPath, XSLT, schema validation, editor support\n3. **LLM Familiarity** - Extensive XML in training data means AI models understand it intuitively\n4. **Extensible Markup** - Literally designed for interweaving text with structure\n5. **Homoiconicity** - Natural representation where code structure mirrors data structure\n\n### The Execution Layer\n\nIdyllic adds a light execution layer with context-driven semantics on top of XML. This enables:\n\n- **Explorative Context Engineering** - Build up context iteratively through function calls\n- **Intelligence Design** - Create patterns of context accumulation that guide AI behavior  \n- **Semantic Clarity** - Each element has clear meaning in the context-building process\n- **Augmented Strings** - Text enriched with mentions, variables, and annotations\n- **Context Combinators** - Functions that compose to build understanding, not just transform data\n\n### Grammar Structure (EBNF-style)\n\n```ebnf\n(* Root Elements *)\ndocument        ::= \u003cdocument [id] [version]\u003e block* \u003c/document\u003e\nagent           ::= \u003cagent [id] [name] [model]\u003e block* \u003c/agent\u003e\ndiff            ::= \u003cdiff\u003e operation+ \u003c/diff\u003e\n\n(* Blocks - The Core Building Units *)\nblock           ::= content-block | executable-block | function-block\n\n(* Content Blocks - Rich Text and Structure *)\ncontent-block   ::= paragraph | heading | list-item | code | quote | separator | data\nparagraph       ::= \u003cp\u003e rich-content \u003c/p\u003e\nheading         ::= \u003ch[1-6]\u003e rich-content \u003c/h[1-6]\u003e\nlist-item       ::= \u003cbulletlistitem\u003e rich-content \u003c/bulletlistitem\u003e\n                  | \u003cnumberedlistitem\u003e rich-content \u003c/numberedlistitem\u003e\n                  | \u003cchecklistitem checked\u003e rich-content \u003c/checklistitem\u003e\ncode            ::= \u003ccode [language]\u003e text \u003c/code\u003e\nquote           ::= \u003cquote [author] [source]\u003e rich-content \u003c/quote\u003e\nseparator       ::= \u003cseparator/\u003e\ndata            ::= \u003cdata [title]\u003e text \u003c/data\u003e\n\n(* Executable Blocks - Context Building *)\nexecutable-block ::= function-call | trigger\nfunction-call    ::= \u003cfncall idyll-fn=\"module:function\"\u003e\n                       [\u003cparams\u003e json \u003c/params\u003e]\n                       [\u003ccontent\u003e rich-content \u003c/content\u003e]\n                     \u003c/fncall\u003e\ntrigger          ::= \u003ctrigger event=\"string\" [debounce]\u003e\n                       [\u003cparams\u003e json \u003c/params\u003e]\n                     \u003c/trigger\u003e\n\n(* Function Blocks - Custom Context Patterns *)\nfunction-block   ::= \u003cfunction title=\"string\" [icon]\u003e\n                       [\u003cfunction:description\u003e text \u003c/function:description\u003e]\n                       \u003cfunction:definition\u003e\n                         (content-block | executable-block)+\n                       \u003c/function:definition\u003e\n                     \u003c/function\u003e\n\n(* Rich Content - Inline Elements *)\nrich-content    ::= (text | styled-text | mention | variable | link | annotation)*\nstyled-text     ::= \u003cstrong\u003e rich-content \u003c/strong\u003e\n                  | \u003cem\u003e rich-content \u003c/em\u003e\n                  | \u003ccode\u003e rich-content \u003c/code\u003e\n                  | \u003cu\u003e rich-content \u003c/u\u003e\n                  | \u003cs\u003e rich-content \u003c/s\u003e\nmention         ::= \u003cmention:[type] id [label]\u003e text \u003c/mention:[type]\u003e\nvariable        ::= \u003cvariable name [prompt]\u003e [text] \u003c/variable\u003e\nlink            ::= \u003ca href\u003e rich-content \u003c/a\u003e\nannotation      ::= \u003cannotation [title] [comment]\u003e rich-content \u003c/annotation\u003e\n\n(* Function Naming Convention *)\nfunction-name   ::= [module \":\"] identifier\nmodule          ::= js-identifier\nidentifier      ::= js-identifier\njs-identifier   ::= /[a-zA-Z_$][a-zA-Z0-9_$]*/\n```\n\n### Key Grammar Insights\n\n1. **Flat Structure** - No deeply nested containers, promoting linear context flow\n2. **Rich Content Everywhere** - Text can contain variables, mentions, and styling\n3. **Function Calls as First-Class** - `\u003cfncall\u003e` blocks are primary building units\n4. **Custom Functions** - Define reusable context-building patterns inline\n5. **Variables in Content** - Not separate from text but embedded within it\n\nThe grammar enforces the philosophy: programs are documents, execution builds context, and meaning emerges from accumulation.\n\n## Technical Details\n\n### Function Naming\n\nAll functions follow the `module:function` pattern with JavaScript identifier constraints:\n\n```typescript\nimport { validateFunctionName, toAzureFunctionName } from '@idyllic-labs/idyll-engine';\n\n// Valid function names\n'demo:echo'        // ✅\n'ai:analyzeText'   // ✅ \n'processData'      // ✅ (no module)\n\n// Invalid (no longer supported)\n'ai:analyze-text'  // ❌ kebab-case not allowed\n\n// Azure Functions compatibility\ntoAzureFunctionName('demo:echo') // → 'demo--echo'\n```\n\n## CLI Usage\n\n```bash\n# Parse a document\nbun run cli parse examples/document-simple.xml\n\n# Validate a document  \nbun run cli validate examples/agent-simple.xml\n\n# Execute a document\nbun run cli execute examples/executable-demo.xml\n\n# Run agent CLI\nbun run agent examples/demo-agent.xml\n```\n\n## API Reference\n\n### Core Functions\n\n- `parseXML(xml: string)` - Parse Idyllic XML to AST\n- `validateDocument(document, context?)` - Validate document structure\n- `createFunctionRegistry(functions)` - Create a function registry\n- `defineFunction(config)` - Define a function with schema and executor\n\n### Agent System API\n\n- `Agent` - AI agent with function execution and memory\n- `ActivityMemory` - Memory management for agent interactions\n- `getModel(modelId)` - Get AI model instance\n\n### Function Naming API\n\n- `toAzureFunctionName(functionName)` - Convert to Azure-compatible names\n- `validateFunctionName(functionName)` - Validate function name format\n- `parseFunctionName(functionName)` - Parse module and function parts\n\n## Examples\n\nExplore our comprehensive examples:\n\n### Basic Examples\n\n- `document-simple.xml` - Basic document structure\n- `executable-demo.xml` - Document with function calls\n- `agent-simple.xml` - Simple agent definition\n- `demo-agent.xml` - Agent with custom functions\n\n### Advanced Examples\n\n- `instrumentation-demo.ts` - Execution hooks and timing\n- `custom-function-instrumentation-demo.ts` - Multi-level context building\n- `recursion-test.ts` - Understanding linear execution model\n- `function-execution-demo.ts` - Direct function execution\n\nRun any TypeScript example:\n\n```bash\nbun run examples/instrumentation-demo.ts\n```\n\n## Development\n\n```bash\n# Install dependencies\nbun install\n\n# Build the package\nbun run build\n\n# Run type checking\nbun run typecheck\n\n# Run tests\nbun run test\n\n# Start agent CLI\nbun run agent\n```\n\n## Documentation\n\n- [Manifesto](./MANIFESTO.md) - Our philosophy and vision for AI programming\n- [Document Execution Specification](./DOCUMENT_EXECUTION_SPEC.md) - Complete execution model\n- [Agent System](./agent/README.md) - Agent architecture details\n\n## The Vision: Community-Driven Intelligence Construction\n\nImagine a world where complex AI capabilities emerge from a community-contributed registry of context-building functions:\n\n```text\ncommunity-functions/\n├── analysis/\n│   ├── code-understanding    # Analyze codebases through context\n│   ├── sentiment-evolution   # Track sentiment across context\n│   └── causal-extraction    # Extract cause-effect relationships\n├── synthesis/\n│   ├── cross-domain-insights # Connect ideas across domains\n│   ├── analogy-discovery    # Find patterns in different contexts\n│   └── thesis-construction  # Build arguments from evidence\n└── specialized/\n    ├── legal-precedent-analysis\n    ├── medical-differential-diagnosis\n    └── architecture-migration-planning\n```\n\nThe key insight: **You're not building agents - you're constructing intelligence** by giving AI composable context-building blocks.\n\nTraditional approach to complex task: Breaks. Too brittle. Too many edge cases.\n\nIdyllic approach: AI naturally composes functions to build understanding:\n\n- Each function adds context\n- AI determines relevance and relationships\n- Complex intelligence emerges from simple primitives\n- No fragile control flow needed\n\nThis is the future we're building towards.\n\n## Community\n\n- **Website**: [idyllic.so](https://idyllic.so) - SaaS version of the engine\n- **Blog**: [idyllic.so/blog](https://idyllic.so/blog)\n- **Discord**: [Join our community](https://discord.gg/idyllic-labs)\n- **Twitter**: [@idylliclabs](https://twitter.com/idylliclabs)\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n```text\nCopyright 2024 Idyllic Labs\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n\n## Acknowledgments\n\n- Built with [Bun](https://bun.sh) for blazing fast development\n- Inspired by the pioneers of homoiconic languages (Lisp, Mathematica)\n- Special thanks to the AI/ML community for pushing the boundaries of what's possible\n\n### Inspirations\n\n- **[Wordware](https://www.wordware.ai/)** - For demonstrating the power of context and documents as programming substrate\n- **[Notion](https://www.notion.so/)** - Pioneered block-based documents that inspired our execution model\n- **[BlockNote](https://www.blocknotejs.org/)** - Our grammar structure is based on their schema design\n- **[Paul Graham](http://www.paulgraham.com/)** - For his foundational work on Lisp and homoiconicity\n- **[LangChain](https://www.langchain.com/)** - Demonstrated the importance of composability in AI systems\n- **[Claude Code](https://claude.ai/code)** - Our collaborative AI partner in designing this language\n\n## Citation\n\nIf you use Idyll Engine in your research, please cite:\n\n```bibtex\n@software{idyll-engine,\n  author = {Idyllic Labs},\n  title = {Idyll Engine: A Context-Building Execution Engine for AI-Native Programming},\n  year = {2024},\n  url = {https://github.com/idyllic-labs/idyll-engine},\n  note = {Available at: \\url{https://idyllic.so}}\n}\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fidyllic-labs%2Fidyll-engine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fidyllic-labs%2Fidyll-engine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fidyllic-labs%2Fidyll-engine/lists"}