l3yx/intentlang: Python 기반 AI 네이티브, 의도 지향 프로그래밍 언어

Python 기반의 AI 네이티브, 의도 지향 프로그래밍 언어

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

이것은 프롬프트가 아닙니다.
이것은 함수 호출도 아닙니다.
이것은 실행 가능한 자연어가 Python에 직접 임베딩된 것입니다.

IntentLang을 사용하면 **의도 기반 프로그램(intent-driven programs)**을 작성할 수 있으며, 이 과정에서 다음과 같은 변화를 가져옵니다:

• 문자열이 더 이상 수동적인 데이터가 아닙니다.
• 자연어가 일급 실행 표현식(first-class executable expression)이 됩니다.
• AI 추론이 프로그램의 제어 흐름에 직접 참여합니다.
• 실제 Python 객체가 프롬프트로 직렬화되는 것이 아니라 런타임에 조작됩니다.

IntentLang은 전통적인 의미에서의 AI 프레임워크가 아닙니다.

이는 **AI 네이티브 프로그래밍(AI-native programming)**에 대한 실험입니다:

*인간의 의도(human intent)*를 범용 프로그래밍 언어 내부의 일급 실행 구성 요소로 취급하는 것입니다.

더 알아보기:

• IntentLang: First Principles와 Intent Engineering으로 AI 에이전트 재구축하기
• IntentLang：以第一性原理与意图工程重建 AI Agent
• AI 네이티브 프로그래밍 언어를 만들기 위해, 저는 CPython의 str을 해킹했습니다.

IntentLang은 AI 에이전트가 작동하는 방식을 근본적으로 재고합니다:

IntentLang은 **인간의 의도(Goal, Contexts, Tools, Input, Strategy, Constraints, Output)**를 형식적으로 표현하는 최초의 프레임워크입니다. 이 요소들은 XML 기반의 Intent IR (Intermediate Representation)로 변환되어 LLM이 코드를 점진적으로 생성하고 인간 의도의 계산 및 반복적 수렴을 실현하도록 안내합니다. 이것은 단순한 프롬프트 엔지니어링이 아니라, 전문가 지식을 재사용 가능하고 검증 가능한 형태로 축적할 수 있게 하는 체계적인 의도 공학(intent engineering)의 구성입니다.

2. 패러다임 전환: 제한된 “함수 호출”에서 자유로운 “코드 실행”으로

IntentLang은 주류 프레임워크에서 발견되는 이산적이고 비효율적이며 엄격하게 스키마로 제한된 Function Calling 패러다임을 완전히 버립니다. AI를 미리 정의된 도구 함수에 가두는 대신, 우리는 AI가 Python 코드를 직접 생성하고 실행할 수 있도록 권한을 부여합니다. 이는 AI의 표현과 연산이 더 이상 고립되고 원자적인 호출이 아니라, 연속적이고 상태를 가지며 튜링 완전한 계산 프로세스라는 것을 의미합니다.

3. 데이터와 명령어 분리: 컨텍스트 한계로부터의 근본적인 탈피

IntentLang에서는 입력 데이터(크기에 관계없이)가 LLM 컨텍스트에 직렬화되어 주입되지 않습니다. AI는 데이터 객체에 대한 메타데이터(이름 및 설명)만 받습니다. 따라서 런타임 시점에 이 인메모리 객체에 접근하기 위한 코드를 생성해야 합니다. 이 모델은 LLM 애플리케이션에서 대규모 입력으로 인해 발생하는 토큰 제한과 비용 문제를 근본적으로 제거합니다.

4. 임베디드 실행: 도구 호출 경계의 제거

초기화된 데이터베이스 연결, 브라우저 인스턴스 또는 복잡한 비즈니스 모델 등 어떤 Python 객체든 AI 실행 환경에 도구로 직접 주입할 수 있습니다. AI가 생성한 코드는 호스트 프로그램과 동일한 실행 흐름 및 런타임 컨텍스트를 공유하며, 객체 속성 접근, 메서드 호출, 그리고 상태의 자연스러운 인식 및 진화를 지속적으로 가능하게 합니다. 이 모델에서 AI는 더 이상 이산적인 도구 호출을 통해 참여하는 것이 아니라, 계산을 완료하기 위해 호스트 코드와 협력하여 프로그램 내에 임베디드 실행 유닛으로 작용합니다.

5. 네이티브 Python 표현: 학습 비용 제로의 '슈퍼 DSL'

IntentLang은 자체적으로 Python을 도메인 특화 언어(DSL)로 취급합니다. 새로운 복잡한 그래프 오케스트레이션 구문이나 YAML 설정을 배울 필요가 없습니다. 만약 여러분이 Python을 작성할 수 있다면, 이미 IntentLang을 알고 있는 것입니다. 이는 학습 장벽을 극적으로 낮추는 동시에 Python의 방대하고 성숙한 생태계를 완전히 활용할 수 있게 합니다.

IntentLang은 Python 3.10 이상을 요구합니다.

pip 사용하기

uv를 사용하는 경우:

pip install intentlang

uv add intentlang

IntentLang은 LLM 구성을 위해 환경 변수를 사용합니다. 프로젝트 루트 디렉터리에 .env 파일을 생성하고 다음 설정을 추가하세요:

# 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
...

from intentlang import Intent
# 원하는 것을 정의합니다.
intent = Intent().goal("모든 짝수를 합산하는 것").input([
...

무슨 일이 일어났나요?

• ✅ 의도가 7가지 요소(Goal, Input, Output)로 공식화되었습니다.
• ✅ AI가 이를 해결하기 위한 Python 코드를 생성했습니다.
• ✅ 코드가 함수 호출이 아닌 런타임에서 실행되었습니다.
• ✅ 입력 데이터는 LLM 컨텍스트에 절대 들어가지 않았습니다 (스키마만 사용됨).

매우 중요: IntentLang은 AI가 생성한 코드를 사용자(host)의 런타임에서 실행합니다.

항상 격리된 환경에서 실행하세요:

• 🐳 Docker 컨테이너
• 📦 샌드박스 Python 환경
• 🔒 가상 머신

이 예시는 AI가 호스트 프로그램에 의해 초기화된 Playwright 객체에 직접 작동하도록 허용하여, 웹 페이지를 열고 제목을 추출하는 연속적인 상호 작용을 가능하게 하는 방법을 보여줍니다.

코드 보기

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

이 예시는 의미론적 인식(semantic recognition) 작업을 처리하는 방법을 보여줍니다.

코드 보기

import os
from typing import List, Literal
from pydantic import Field
...

IntentLang의 핵심은 Intent 객체 구성에 있습니다. 이 객체는 자연어 의도를 실행 가능한 Python 코드로 변환하고 호스트 프로그램과의 원활한 협업을 가능하게 합니다.

Intent는 IntentLang 프레임워크의 최소 논리 단위로, 특정 작업을 완료하는 데 AI가 필요한 모든 정보를 캡슐화합니다. Intent 객체는 메서드 체이닝(method chaining)을 통해 구성되며, 작업의 각 요소를 명확하게 정의합니다.

Intent를 정의하는 7가지 요소:

.goal(goal: str)

목적(Purpose): AI가 달성해야 할 **궁극적인 목표(ultimate goal)**를 명확하게 설명합니다. 이는 LLM이 작업을 이해하기 위한 핵심 지침입니다.

intent = Intent().goal("Calculate the sum of even numbers")

.ctxs(ctxs: list[str])

목적: LLM에 추가적인 **문맥 정보(contextual information)**를 제공합니다. 이는 LLM이 작업 배경이나 도메인별 지식을 더 잘 이해하도록 돕는 일반 텍스트 설명입니다.

intent = Intent().ctxs([
"integers ending in 7 are lucky numbers",
"4 is considered an unlucky number"
...

.tools(tools: list[Callable | Tuple[object, str, str]])

목적: 사용 가능한 **도구(tools)**를 AI의 실행 환경에 주입합니다. 이 도구들은 일반적인 Python 함수이거나 호스트 프로그램에서 이미 초기화된 **모든 Python 객체(any Python objects)**일 수 있습니다.

주요 특징: 전통적인 Function Calling은 함수로 제한되는 것과 달리, IntentLang은 모든 Python 객체를 도구로 주입할 수 있게 합니다. 이는 AI가 직렬화 및 역직렬화 과정 없이도 객체의 메서드를 직접 호출하고, 속성에 접근하며, 객체 수준의 연속적인 연산을 수행할 수 있음을 의미합니다.

사용법: 요소가 함수이거나 (object, name, description) 튜플일 수 있는 리스트를 받습니다.

intent = Intent().tools([
check_lucky_number, # function
(browser_context, "context", "Playwright context") # object
...

.input(input: IntentIO | None = None, **field_definitions)

목적: 이 의도(intent)를 실행할 때 AI가 접근할 수 있는 **입력 데이터(input data)**를 정의합니다. 이 데이터는 Python 객체에 대한 참조(references) 형태로 전달됩니다.

주요 특징: 입력 데이터 자체는 직렬화되어 컨텍스트로 LLM에 전송되지 않습니다. LLM은 이러한 데이터 객체에 대한 **메타데이터(이름 및 설명)**만 받습니다. AI는 필요할 때 이 인-메모리 객체들에 접근하고 조작하기 위해 Python 코드를 생성해야 합니다.

사용법:

동적 정의: 키워드 인자(keyword arguments)를 통해 입력 필드를 정의합니다. 각 인자는 (값, 설명) 튜플입니다.
사전 정의 모델: 초기화된 IntentIO를 직접 전달합니다.

subclass object.

# Dynamic definition
intent = Intent().input(
numbers=([1,2,3,4,5], "list of integers")
...

.how(how: str)

목적: 목표를 달성하는 고수준 전략 또는 구현 접근 방식을 제공합니다. 이는 LLM이 코드를 생성할 때 특정 방법론을 따르도록 안내합니다.

intent = Intent().how("Process each item one by one")

.rules(rules: list[str])

목적: 실행 중에 따라야 하는 특정 제약 조건 또는 행동 지침을 설정합니다. 이 규칙들은 LLM이 코드 생성 논리를 정교화하고 출력이 기대치를 충족하도록 보장하는 데 도움을 줍니다.

intent = Intent().rules([
"Must validate all inputs before processing",
"Handle errors gracefully"
...

.output(output: Type[IntentIO] | None = None, **field_definitions)

목적: 의도(intent)를 성공적으로 완료한 후 AI가 생성해야 하는 결과 구조를 정의합니다. 이는 AI가 예상되는 Pydantic 모델 형식으로 데이터를 반환하도록 강제하여 구조화되고 검증 가능한 출력을 보장합니다.

사용법:

동적 정의 (Dynamic definition): 키워드 인수를 통해 출력 필드를 정의합니다. 각 인수는 (타입, 설명) 튜플입니다.미리 정의된 모델 (Predefined model): IntentIO를 상속받는 Pydantic 모델 클래스를 직접 전달할 수 있습니다.

# Dynamic definition
intent = Intent().output(
sum=(int, "sum of even numbers")
...

Intent를 정의한 후에는 compile 및 run 메서드를 통해 실행할 수 있습니다.

세부 정보 보기 (View Details)

• :.compile(engine_factory: EngineFactory | None = None, max_iterations: int = 30, cache: bool = False, record: bool = True) -> Executor`

목적: Intent 객체를 실행 가능한 Executor 인스턴스로 "컴파일"합니다. 이 과정은 최종 프롬프트를 생성하고 실행 환경을 준비합니다.매개변수 (Parameters):
engine_factory: 현재는 LLMEngineFactory만 사용 가능합니다.max_iterations: 무한 루프를 방지하기 위한 최대 반복 횟수입니다(기본값 30).cache:

: 캐싱 활성화 여부 (기본값 False), Jupyter Notebook 캐시에서 코드 재사용.record

: 실행 프로세스를 Notebook에 기록할지 여부 (기본값 True).

사용법: 실행 프로세스에 대해 더 세밀한 제어가 필요할 때 이 메서드를 사용합니다.

:.run() -> IntentResult

목적: 이것은 Intent를 자동으로 컴파일하고 즉시 실행하여 최종 결과를 반환하는 편리한 메서드입니다. 관계: intent.run()을 호출하는 것은 본질적으로 intent.compile().run()과 동일합니다.

주요 기능: run()은 AI가 필요한 모든 코드 생성 및 실행 단계를 완료할 때까지 기다린 후, AI가 생성한 구조화된 데이터를 담고 있는 IntentResult 객체를 최종적으로 반환하는 비동기(asynchronous) 메서드입니다. Intent는 또한 동기 버전인 run_sync()를 제공합니다.

Executor는 Intent의 실행 엔진입니다. 이는 구성된 Intent 객체를 LLM이 이해할 수 있는 프롬프트로 변환하고, 이어서 LLM이 생성한 Python 코드를 Python 런타임 환경에서 반복적으로 실행하는 역할을 합니다. Executor는 AI가 OutputModel 정의를 준수하는 결과를 성공적으로 생성하거나 설정된 최대 반복 횟수에 도달할 때까지 계속 반복합니다.

Runtime은 top-level await를 지원하는 임베디드 Python REPL(Read-Eval-Print Loop) 환경입니다.

핵심 기능:

• 코드 실행: LLM이 생성한 Python 코드를 실행합니다.
• 관찰 피드백 (Observation Feedback): 코드 실행 중 발생하는 모든 print 출력을 캡처하여

호스트 프로그램과 동일한 프로세스 공간을 공유하여 AI가 생성한 코드가 호스트 프로그램으로부터 전달된 Python 객체(예를 들어 input 및 tools에서 정의된 객체)에 직접 접근하고 조작할 수 있게 함으로써 진정한 임베디드 협업을 달성합니다.

곧 출시 예정:

• Intent 시각화 UI (Agent Pattern Graph → IntentLang 변환)

• 더 많은 실제 사례

장기 비전:

• LLM에서의 코드 레벨 의도 표현 네이티브 지원

• 도메인별 패턴을 위한 Intent 마켓플레이스

IntentLang은 淚笑에 의해 생성 및 유지 관리됩니다.

저와 연결하기:

• Twitter: @leixiao_cn

• Blog: l3yx.github.io

• GitHub: l3yx

• Organ: chainreactors

질문, 제안 또는 협업 문의는 다음으로 연락 주십시오: