Productive-Superintelligence/lllm

LLLM은 고급 에이전트 시스템 (advanced agentic systems) 개발을 위한 경량 프레임워크입니다. 사용자가 100줄 미만의 코드 (LoC)로 복잡한 에이전트 시스템을 구축할 수 있게 해줍니다. 미니멀리즘, 모듈성 (modularity), 신뢰성 (reliability)을 우선시하며, 일상적인 채팅을 넘어선 복잡하고 최첨단인 에이전트 시스템에 특히 적합합니다. 이러한 분야는 깊은 아키텍처 커스터마이징 (architectural customization)과 매우 다양한 요구사항을 필요로 하지만, 개발자와 연구자들은 예외 처리 (exception handling), 출력 파싱 (output parsing), API 오류 관리 (API error management)와 같은 저수준의 복잡성을 관리해야 하는 부담을 자주 겪습니다. LLLM은 높은 수준의 캡슐화 (encapsulation)와 유연한 실험에 필요한 단순성 사이의 균형을 맞춘 필수적인 추상화 (abstractions)를 제공함으로써 이 간극을 메웁니다. 또한 불필요한 간접 참조 (indirection)를 줄여 코드를 명확하고, 압축적이며, 이해하기 쉽게 만들어, 연구자와 개발자가 핵심 연구 질문에 집중할 수 있도록 다양한 프로젝트 요구사항에 맞춘 커스터마이징을 용이하게 합니다. 자세한 문서는 https://lllm.one 을 참조하세요.

주요 설계 아이디어: 프로그램으로서의 에이전트 시스템 (agents + prompts + tactics), 각 에이전트의 내부 정신 상태 (internal mental state)로서의 대화 (dialog), 선언 (declaration)으로서의 설정 (configuration). 전체 설계 철학은 아키텍처 개요 (Architecture Overview)를 참조하세요.

pip install lllm-core

설정이 필요 없습니다. API 키를 설정하고 실행하세요:

pip install lllm-core
export OPENAI_API_KEY=sk-... # 또는 ANTHROPIC_API_KEY 등

from lllm import Tactic
# 한 줄 채팅
response = Tactic.quick("What is the capital of France?")
...

그게 전부입니다 — lllm.toml도, 폴더 구조도, 서브클래싱 (subclassing)도 필요 없습니다.

지원되는 제공업체 (providers) (LiteLLM을 통해):

• OpenAI:
  model="gpt-4o"

+OPENAI_API_KEY

• Anthropic:
  model="claude-opus-4-6"

+ANTHROPIC_API_KEY

• 기타 LiteLLM이 지원하는 모든 제공업체

프로젝트가 성장함에 따라 점진적으로 구조를 도입할 수 있습니다:

lllm create my-app
cd my-app
uv sync --extra dev
...

생성된 프로젝트에는 lllm.toml, prompts/, configs/, tactics/, main.py 및 스모크 테스트 (smoke test)가 포함됩니다. lllm create

번들로 제공되는 템플릿을 사용하며, lllm-template.toml을 포함하는 로컬 템플릿 폴더를 렌더링할 수도 있습니다.

내장 템플릿 (Built-in templates):

템플릿	사용 사례
minimal	실행 가능한 가장 작은 LLLM 앱을 원하는 경우
pipeline	플래너(planner)/작성자(writer)/검토자(reviewer) 멀티 에이전트 워크플로우 (multi-agent workflow)를 원하는 경우
service	FastAPI를 사용할 준비가 된 택틱 서비스 (tactic service)를 원하는 경우
proxy	API/도구 인터페이스를 LLLM 프록시 (proxy)로 래핑(wrap)하려는 경우
research	배치 스크립트 (batch scripts)와 데이터가 포함된 실험 워크스페이스를 원하는 경우

또한 수동으로 구조를 추가할 수 있습니다:

설정 파일 추가— lllm.toml.example을 lllm.toml로 복사한 뒤, 프롬프트/프록시 폴더를 지정하세요.
프롬프트를 파일로 이동— Prompt 객체가 포함된 Python 파일들을 prompts/ 폴더 아래에 두면, 디스커버리 (discovery)를 통해 자동으로 등록됩니다.
YAML에서 에이전트 정의— 멀티 에이전트 택틱 (multi-agent tactics)을 위해 AgentSpec 설정을 사용하세요.
서브클래싱 (Subclass)— 여러 에이전트를 오케스트레이션 (orchestrate)하기 위해 Tactic의 call()을 구현하세요.

각 단계의 구체적인 패턴은 examples/를 참조하세요.

tutorials/에는 기본 원리부터 프로덕션 패턴 (production patterns)까지 프레임워크 전체를 안내하는 단계별 Jupyter 노트북이 있습니다:

노트북	수준	주제
01_getting_started.ipynb	초급	Tactic.quick(), Agent, 3단계 대화 패턴, 멀티 턴 대화 (multi-turn conversations), 대화 포킹 (dialog forking), Prompt 템플릿, DefaultTagParser, Pydantic 구조화된 출력 (structured output), 컨텍스트 관리 (context management)
02_tactics_and_agentic_systems.ipynb	중급	Tactic 서브클래싱, 멀티 에이전트 파이프라인 (multi-agent pipelines), 서브 택틱 합성 (sub-tactic composition), TacticCallSession, bcall / acall / ccall, LogStore, 세션 태깅 (session tagging), 비용 집계 (cost aggregation)
03_advanced_features.ipynb	고급	@tool 심층 분석, MCP 서버, 프록시 시스템, 인터프리터 모드 (interpreter mode), Jupyter 샌드박스 (sandbox), lllm.toml 패키지, 스킬 (Skills), 명명된 런타임 (named runtimes), 스트리밍 (streaming), 이미지 입력, 커스텀 핸들러 (custom handlers)

각 노트북은 독립적이며 상단에 환경 설정 지침이 포함되어 있습니다. 헬퍼 유틸리티 (Helper utilities)와 샘플 패키지는 tutorials/helpers/ 및 tutorials/packages/에 있습니다.

전체 인덱스는 examples/README.md를 참조하세요.

간략한 지도:

독립형 스크립트 (Standalone scripts) — 대부분 하나의 API 키만 필요하며, 추가 설정이 필요 없습니다:

스크립트	내용
basic_chat.py	Tactic.quick() — 설정이 필요 없는 단일 에이전트 (single-agent) 채팅
multi_turn_chat.py	멀티턴 (Multi-turn) 히스토리, 대화 fork()
tool_use.py	@tool 데코레이터 (decorator), 함수 호출 (function calling), 진단 (diagnostics)
package_tool_refs.py	결합/분리된 일반 도구, 전술 도구 (tactic tools), 프록시 (proxies)를 위한 패키지 스타일 도구 참조
structured_output.py	Prompt(format=MyModel) — Pydantic 구조화된 출력 (structured output)

고급 스크립트 (Advanced scripts) (examples/advanced/에 위치) — 환경 변수에서 제공자 (provider)를 자동 감지합니다:

스크립트	내용
multi_agent_tactic.py	커스텀 Tactic 서브클래스 (subclass), 2-에이전트 파이프라인 (pipeline)
session_logging.py	SQLite LogStore, 세션 쿼리 (querying)
batch_processing.py	bcall(), ccall() 병렬 실행 (concurrent execution)
proxy_interpreter.py	proxy 설정, run_python 도구, 상태가 유지되는 AgentInterpreter

전체 패키지 예시 — examples/code_review_service/:

lllm.toml, 프롬프트 파일, 전술 (tactic) 파일, 그리고 상속 기능이 포함된 YAML 설정이 포함된 자립형 (self-contained) LLLM 패키지이며, FastAPI HTTP 서비스로 래핑(wrapped)되어 있습니다. 전체 문서는 code_review_service/README.md를 참조하세요.

cd examples/code_review_service
export OPENAI_API_KEY=sk-...
python service.py --demo # CLI 데모, 웹 서버 없음
...

내장된 프록시 (금융 데이터, 검색 등)는 해당 모듈이 임포트(import)될 때 자동으로 등록됩니다. Proxy()를 직접 호출할 계획이라면 다음 중 하나를 수행해야 합니다:

• [proxies] 섹션이 포함된 lllm.toml을 설정하여, 시작 시 탐색(discovery) 과정에서 프록시 폴더를 임포트하도록 하거나,
• load_builtin_proxies()를 호출하여 패키징된 모듈을 임포트하거나,
• 필요한 프록시를 수동으로 임포트합니다 (예: from lllm.proxies.builtin import exa_proxy).

이는 lllm.toml의 [prompts]를 통해 프롬프트가 자동 등록되는 방식과 동일합니다.

프록시가 로드되면 Proxy().available()을 호출하여 사용 가능한 항목을 확인할 수 있습니다.

리소스 URL 기반의 에이전트 레벨 도구 (Agent-level tools by resource URL) — 에이전트 설정(config)에 tools:를 추가하면, 매 프롬프트 턴(prompt turn)마다 패키지 공유 기능(package-shared capabilities)을 사용할 수 있습니다:

global:
  tools:
    - shared_pkg.tools:search
...

일반적인 @tool 구현체와 전술 참조(tactic refs)는 직접적인 프롬프트 도구(prompt tools)가 됩니다. 프롬프트 Function 선언은 정확한 키(exact key)를 통해 동일 패키지의 @tool 구현체와 바인딩됩니다. 프록시 참조(Proxy refs)는 프록시 프로그래밍 인터페이스(proxy programming surface)를 활성화합니다.

이를 통해 두 가지 일반적인 도구 스타일을 사용할 수 있습니다: 선언과 구현이 결합된 경우 데코레이터가 적용된 @tool 함수나 URL을 전달하거나, 프롬프트/설정(config)에 Function 선언을 두고 런타임(runtime)이 정확한 키를 가진 패키지 구현체를 매칭하도록 하는 방식입니다. 전술 도구(Tactic tools)와 프록시(proxies)는 에이전트 서브시스템(agentic subsystems) 및 프로그래밍 기반 API 접근을 위해 이러한 스타일들을 어댑터(adapters)로 구현한 것입니다.

에이전트 레벨 프록시 도구 주입 (Agent-level proxy tool injection) — 에이전트 설정에 proxy: 블록을 추가하면 LLLM이 자동으로 run_python 및 query_api_doc 도구와 함께 API 디렉토리 블록을 시스템 프롬프트(system prompt)에 주입합니다:

agent_configs:
  - name: analyst
    proxy:
...

그러면 에이전트는 CALL_API(endpoint, params)를 사용하는 Python 코드로 run_python(code)를 호출합니다. 변수는 동일 세션 내의 호출 간에 유지됩니다. 실행 가능한 예제는 advanced/proxy_interpreter.py를, 전체 참조는 Proxies & Sandbox를 확인하세요.

시작을 위한 lllm.toml.example 파일이 리포지토리 루트(repo root)에 있습니다. 이를 프로젝트 엔트리 포인트(entry point) 옆으로 복사하고 폴더 경로를 수정하세요:

cp lllm.toml.example lllm.toml

샘플 설정은 examples/autodiscovery/prompts/ 및 examples/autodiscovery/proxies/를 가리키고 있으며, 즉시 실험해 볼 수 있는 작동하는 프롬프트(examples/hello_world)와 프록시(examples/sample)를 제공합니다.

pytest로 테스트를 실행하세요:

pytest tests/

컴퓨터 사용 에이전트 (Computer Use Agent, CUA) – lllm.tools.cua는 Playwright와 OpenAI Computer Use API를 통해 브라우저 자동화를 제공합니다. 이는 아직 발전 중이며 예고 없이 변경될 수 있습니다.

응답 API 라우팅 (Responses API Routing) – api_type = "response"를 설정하여 OpenAI의 Responses API를 선택적으로 사용할 수 있습니다.

에이전트당(per agent). 이를 통해 네이티브 웹 검색/컴퓨터 사용(computer-use) 도구를 사용할 수 있지만, 현재는 OpenAI만을 대상으로 합니다.기술(Skills)– 더 복잡한 베이스 에이전트(base agents)를 정의하기 위한 용도.

• 프로바이더(providers) 시스템 리팩토링: LiteLLM 인보커 (invokers/)

• 레지스트리(registry)를 런타임(runtime.py) 및 디스커버리 시스템(discovery.py)으로 리팩토링

• 프롬프트 모델 및 프롬프트 관리(prompt.py) 리팩토링

• 프롬프트 구성(composition) 및 상속

• 패키지 키(Package-key) 도구 선언 및 구현

• 임시(ad-hoc) 설계 정리

• 더 나은 파싱(parsing) 시스템, 더 직관적인 인자(argument) 전달

• 에러(error), 예외(exception), 인터럽트(interrupt)에 대한 더 나은 처리 시스템

• 메시지 및 대화(dialog) 모델/상태 관리 리팩토링, 더 나은 인자 전달 (dialog.py)

• 에이전트(agent) 모델, 에이전트 호출(agent call) 리팩토링 (agent.py)

• 전술(tactics) 리팩토링 (tactic.py)

• 설정(config) 및 패키지 시스템 리팩토링 (config.py, lllm.toml, 등)

• lllm.toml을 사용하는 패키지 시스템

  • 네임스페이스화된 리소스 URL (pkg.section:resource)
  • 재귀적 로딩 및 사이클 탐지(cycle detection)를 포함한 의존성 트리(Dependency tree)
  • 별칭(Alias) 지원 (패키지를 위한 as, 가상 폴더 접두사를 위한 under)

• 지연 로딩(lazy loading)을 지원하는 통합된 ResourceNode 기반 레지스트리

• 병렬 실험을 위한 명명된 런타임 (load_runtime, get_runtime)

• 프로젝트 루트의 lllm.toml으로부터 자동 초기화

• 에이전트 설정 YAML:

  • global 기본값, agent_configs 리스트, 딥 머지(deep merge)를 지원하는 base 상속

• 인라인 system_prompt 또는 system_prompt_path 해결을 지원하는 AgentSpec

• 재귀적 설정 상속을 위한 resolve_config()

• 편의 로더(Convenience loaders): load_prompt, load_tactic, load_proxy, load_config, load_resource

• 패키지 시스템 포함

• 로거 (CLI 로깅), 재생 가능한 로깅 시스템 및 출력 시스템 (log.py, utils.py)

• 플러그형 백엔드 (LocalFileBackend, SQLiteBackend, NoOpBackend)를 갖춘 LogStore

• 태그 기반 인덱싱 및 필터링, 비용 집계(cost aggregation), 내보내기(export) 헬퍼

• 파일 레이아웃 및 별칭과 무관한 안정적인 pkg::name 전술 식별자

• ColoredFormatter 및 setup_logging

터미널 출력용 - 편의 기능 팩토리 (Convenience factories):
local_store

, sqlite_store

, noop_store

• 빠른 모드, 설정 없이 5줄의 코드로 간단한 시스템 구축 가능.

• 프록시 기반 도구 호출 (Proxy-based tool-calling), 대화 내 미니 인터프리터 (proxies/)

• 대화 크기 초과 시 가지치기를 위한 기본 컨텍스트 매니저 (Context Manager)

• 에이전트 설정 내 스킬 (skills) 지원, https://agentskills.io 참조

• 전술 (Tactics), 프롬프트 (Prompts), 프록시 (Proxies), 설정 (Configs) 등을 포함한 패키지 공유 및 관리 시스템.

• 애드온 (Add-on): 로깅 시스템 기반의 분석 도구, 예: 비용 분석, 대화 분석 등. 기본적으로 로깅 DB를 위한 GUI를 제공하며, Streamlit, Dash, Panel 등을 사용하여 기본 대시보드가 포함된 앱으로 내보내기 가능.

• 애드온 (Add-on): 고급 샌드박스 (Advanced sandbox), 예: 브라우저 샌드박스, 코드 샌드박스 등. OpenSandbox와 같은 샌드박스 휠 (sandbox wheels)을 사용할 수도 있음 (sandbox/). 또는 외부에서 작동할 수 있으므로 코어 패키지에는 포함하지 않을 수도 있음.

• 문서화를 위해 Mintlify 사용 고려

• 튜닝/학습을 위한 그래디언트 모드 (Gradient mode)