Intent-Driven Embedded AI Programming Framework

An AI-Native, Intent-Oriented Programming Language built on Python

⚡️ IntentLang in One Glance: When Natural Language Becomes Code

import socket
from intentlang import MagicIntent
MagicIntent.hack_str(cache=True)

# Natural language as an executable expression
data = [1, 2, 3, 4, 5]
if "sum of all even numbers".i(data).o(int) > 5:
    print("Result is greater than 5")

# Natural language controlling real objects
sock = socket.socket()
"Connect to example.com and send an HTTP GET request".i(sock).r("Do not receive data, only send, and keep the socket open")()
print(sock.recv(15).decode())

This is not a prompt. This is not function calling. This is executable natural language embedded directly into Python.

IntentLang allows you to write intent-driven programs, where:

• Strings are no longer passive data
• Natural language becomes a first-class executable expression
• AI reasoning participates directly in program control flow
• Real Python objects are manipulated at runtime, not serialized into prompts

IntentLang is not an AI framework in the traditional sense.

It is an experiment in AI-native programming:
treating human intent as a first-class, executable construct inside a general-purpose programming language.

Read more:

• IntentLang: Rebuilding AI Agents with First Principles and Intent Engineering
• IntentLang：以第一性原理与意图工程重建 AI Agent
• 为了创造 AI-native programming language, 我 hack 了 CPython 的 str

Why IntentLang?

IntentLang fundamentally rethinks how AI agents work:

| Traditional Agents | IntentLang | |-------------------|------------| | 🔧 Discrete function calls | 🎯 Continuous code execution | | 📦 Data in context | 🔗 Data in runtime (Schema-only) | | 🔌 Tools as external APIs | 🧬 Tools as embedded objects | | 📝 Prompt engineering | 🏗️ Intent engineering |

<details> <summary><b>1. Precise Modeling and Computation of Intent: Human Intent as a First-Class Citizen</b></summary>

IntentLang is the first framework to formally represent human intent (Goal, Contexts, Tools, Input, Strategy, Constraints, Output). These elements are transformed into an XML-based Intent IR (Intermediate Representation), guiding the LLM to progressively generate code and realize the computation and iterative convergence of human intent. This is not mere prompt engineering, but a systematic construction of intent engineering, allowing expert knowledge to be accumulated in a reusable and verifiable form.

</details> <details> <summary><b>2. Paradigm Shift: From Constrained “Function Calling” to Free “Code Execution”</b></summary>

IntentLang completely abandons the discrete, inefficient, and strictly schema-constrained Function Calling paradigm found in mainstream frameworks. Instead of confining AI to predefined tool functions, we empower it to generate and execute Python code directly. This means AI expression and operation are no longer isolated, atomic calls, but a continuous, stateful, and Turing-complete computational process.

</details> <details> <summary><b>3. Separation of Data and Instructions: A Fundamental Break from Context Limitations</b></summary>

In IntentLang, input data (regardless of size) is not serialized and injected into the LLM context. The AI receives only metadata about the data objects (names and descriptions). It must generate code to access these in-memory objects on demand at runtime. This model fundamentally eliminates token limits and cost issues caused by large inputs in LLM applications.

</details> <details> <summary><b>4. Embedded Execution: Eliminating Tool Invocation Boundaries</b></summary>

You can inject any Python object—whether an initialized database connection, a browser instance, or a complex business model—directly into the AI execution environment as a tool. Code generated by the AI shares the same execution flow and runtime context as the host program, enabling continuous access to object attributes, method invocations, and natural perception and evolution of state. In this model, the AI no longer participates through discrete tool calls, but acts as an embedded execution unit within the program, collaborating with host code to complete computation.

</details> <details> <summary><b>5. Native Python Expression: A “Super DSL” with Zero Learning Cost</b></summary>

IntentLang treats Python itself as its domain-specific language (DSL). There is no need to learn new, complex graph orchestration syntaxes or YAML configurations. If you can write Python, you already know IntentLang. This dramatically lowers the learning barrier while allowing full leverage of Python’s vast and mature ecosystem.

</details>

Quick Start

Installation

IntentLang requires Python 3.10 or higher.

Using pip:

pip install intentlang

Using uv:

uv add intentlang

Configuration

IntentLang uses environment variables for LLM configuration. Create a .env file in your project root directory and add the following settings:

# OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
# OPENAI_BASE_URL=https://open.bigmodel.cn/api/paas/v4
OPENAI_BASE_URL=https://api.deepseek.com
OPENAI_API_KEY=
OPENAI_MODEL_NAME=
# OPENAI_EXTRA_BODY={}

Your First Intent

from intentlang import Intent

# Define what you want
intent = Intent().goal("Sum all even numbers").input(
    numbers=([1,2,3,4,5,6], "list of integers")
).output(sum=(int, "sum of even numbers"))

# Execute the computation
result = intent.run_sync()
print(result.output.sum)  # Output: 12
print(result.usage.model_dump_json())

What just happened?

• ✅ Intent formalized into 7 elements (Goal, Input, Output)

• ✅ AI generated Python code to solve this

• ✅ Code executed in runtime, not function calls

• ✅ Input data never entered LLM context (only schema did)

Security Notice

CRITICAL: IntentLang executes AI-generated code in your runtime.

Always run in isolated environments:

• 🐳 Docker containers

• 📦 Sandboxed Python environments

• 🔒 Virtual machines

Examples

Web Automation: Playwright Continuous Operations

This example demonstrates how to allow the AI to directly operate on a Playwright object initialized by the host program, enabling continuous interaction for opening a web page and extracting its title.

<details> <summary>View Code</summary>

import asyncio
from intentlang import Intent
from playwright.async_api import async_playwright, Page


async def test():
    playwright = await async_playwright().start()
    browser = await playwright.chromium.launch(headless=False)
    context = await browser.new_context()

    url = "https://l3yx.github.io/"

    intent_a = (
        Intent()
        .goal("Open the url")
        .input(
            # Format: name=(value, "description")
            url=(url, "Target URL to open")
        )
        .tools([
            # Formats: function, or (object, "name", "description")
            (context, "context", "Playwright Context instance (async API)")
        ])
        .output(
            # Format: name=(type, "description")
            page=(Page, "Playwright Page instance")
        )
    )
    page = (await intent_a.run()).output.page
    print(page)

    intent_b = (
        Intent()
        .goal("Get webpage title")
        .input(
            page=(page, "Playwright Page instance")
        )
        .output(
            title=(str, "Webpage title")
        )
    )
    title = (await intent_b.run()).output.title
    print(title)

asyncio.run(test())

</details>

Text Analysis: Movie Review Sentiment Classification

This example demonstrates how to handle a semantic recognition task.

<details> <summary>View Code</summary>

import os
from typing import List, Literal
from pydantic import Field
from intentlang import Intent, LLMConfig, IntentIO
from intentlang.tools import create_reason_func


llm_config = LLMConfig(
    base_url=os.getenv("OPENAI_BASE_URL"),
    api_key=os.getenv("OPENAI_API_KEY"),
    model_name=os.getenv("OPENAI_MODEL_NAME"),
    extra_body=os.getenv("OPENAI_EXTRA_BODY")
)


movie_reviews = """
This movie has a gripping plot with constant twists—my adrenaline was through the roof, highly recommend!
The visual effects are mind-blowing; the VFX team deserves an Oscar—pure audiovisual feast!
The acting is spot-on, especially the protagonist's inner turmoil feels so real—I was in tears.
Pacing is a bit slow, but the philosophy is profound; it leaves you thinking long after, worth a rewatch.
Avoid this one—full of plot holes, logic collapses, wasted two hours of my life.
"""


class ReviewResult(IntentIO):
    review: str = Field(description="Original evaluation content")
    sentiment: Literal["positive", "negative",
                       "mixed"] = Field(description="Sentiment Classification")
    reason: str = Field(description="Classification Reasons")


class Result(IntentIO):
    reviews: List[ReviewResult] = Field(
        description="Sentiment analysis results for each review")


intent = (
    Intent()
    .goal("Sentiment categorization for each movie review")
    .input(
        movie_reviews=(movie_reviews, "Contains multiple reviews, one per line")