Monan-AI/monan-sdk

Monan은 현재 활발히 개발 중인 단계 (Alpha)입니다. 일부 기능은 변경될 수 있습니다. 저희가 버전 1.0에 도달할 수 있도록 PR (Pull Requests), Issues, 그리고 피드백을 통한 커뮤니티 협업을 환영합니다.

Bun 기반의 네이티브 AI 에이전트(Native AI Agents)를 위한 궁극의 SDK입니다. 베어메탈(bare-metal) 성능, 임베디드 벡터(embedded vectors), 그리고 복잡한 워크플로(workflows)를 통해 로컬 에이전트를 구축, 오케스트레이션(orchestrate) 및 확장하세요.

Monan은 AI 오케스트레이션의 지연 시간(latency)과 복잡성을 제거하기 위해 설계된 프레임워크입니다. Python 기반 솔루션과 달리, Monan은 Bun의 네이티브 아키텍처를 활용하여 로컬 추론 (local inference), SQLite 벡터 저장소 (vector storage), 그리고 워크플로 오케스트레이션 (workflow orchestration)을 하나의 응집된 도구로 제공합니다.

bun add monan-sdk

CLI를 사용하려면 (실행 및 테스트에 필수):

bun add -g monan-sdk

Monan에서는 코드로 에이전트를 정의하지만, 실행 (채팅 또는 API)은 CLI에 의해 관리됩니다. 이는 최적화와 표준화를 보장합니다.

Ollama에서 사용 가능한 모든 모델을 사용할 수 있습니다. 문자열 형식에 주의하세요: ⚠️ 로컬 모델 (Local Models): <model-name>:<parameter-amount>

중요: 로컬 모델을 사용할 때는 에이전트를 실행하기 전에 별도의 터미널에서 ollama serve를 실행해야 합니다.

클라우드 모델 (Cloud Models): OpenAI, Anth Anthropic 및 기타 모델에 접근할 수 있도록 OpenRouter를 지원합니다.

1. src 폴더 내에 agent.ts 파일을 생성합니다:

import { Agent } from 'monan-sdk';
// 에이전트를 정의하고 내보냅니다
export const assistant = new Agent({
...

2. 터미널에서 실행 (대화형 모드 - Interactive Mode):
빠른 테스트를 위해 채팅을 시뮬레이션합니다.

monan test assistant:src.agent

3. API로 실행 (프로덕션 모드 - Production Mode):
최적화된 Elysia 서버를 자동으로 구동합니다.

monan run assistant:src.agent --port 3000
# 엔드포인트 주소: http://localhost:3000
# 문서: http://localhost:3000/docs

모든 사람이 GPU 장비를 갖추고 있는 것은 아닙니다. Monan은 OpenRouter와 네이티브하게 통합되어 있어, 외부 제공업체 (OpenAI, Anthropic, Gemini)를 쉽게 사용할 수 있습니다.

보안 우선 (Security First): 외부 제공업체를 사용할 때, Monan은 기본적으로 **PII 마스킹 (PII Masking)**을 활성화합니다 (maskPII: true

)). 이는 컨텍스트를 클라우드로 전송하기 전에 민감한 데이터(이메일, 전화번호, API 키)를 자동으로 비식별 처리합니다.

import { Agent } from 'monan-sdk';
const cloudAgent = new Agent({
name: "CloudAssistant",
...

에이전트의 행동과 성격을 안내하기 위해 커스텀 시스템 프롬프트 (System Prompt)를 정의하세요. 만약 systemPrompt가 제공되지 않으면, Monan은 에이전트의 이름과 설명을 기반으로 이를 자동으로 생성합니다.

import { Agent } from 'monan-sdk';
const specialistAgent = new Agent({
name: "DataAnalyst",
...

시스템 프롬프트 우선순위 (System Prompt Priority):

• systemPrompt가 제공되면, 이를 기본 시스템 지침으로 사용합니다. 제공되지 않으면 Monan이 자동으로 "You are {name}. {description}"를 생성합니다.

• 메시지 기록 (Message History)에 추가적인 시스템 메시지가 있는 경우, 시스템 프롬프트가 해당 메시지들 앞에 추가됩니다.

작은 로컬 모델 (Small local models)은 특정 지침을 수행하는 데 어려움을 겪는 경우가 많습니다. **LoRA/QLoRA 어댑터 (LoRA/QLoRA adapters)**를 로컬에서 사용하려면, 먼저 Ollama에서 커스텀 모델을 생성해야 합니다. 이는 엔진 레벨에서 어댑터 가중치를 병합함으로써 최대의 성능을 보장합니다.

1단계: Modelfile 생성
프로젝트 루트에 Modelfile이라는 이름의 파일을 생성합니다:

FROM gemma3:4b
# GGUF 어댑터 경로
ADAPTER ./adapters/finance-v1.gguf
...

2단계: 커스텀 모델 빌드
터미널에서 다음 명령어를 실행합니다:

ollama create finance-expert -f Modelfile

3단계: Monan에서 모델 사용
이제 생성한 새로운 커스텀 모델의 이름을 참조하기만 하면 됩니다.

const specializedAgent = new Agent({
name: "FinanceExpert",
model: "finance-expert", // <--- 2단계에서 생성한 이름
...

복잡한 시스템의 경우, 모든 작업에 무거운 모델을 사용해서는 안 됩니다. **라우터 (Router)**를 사용하면 의도(Intent)나 복잡성에 따라 요청을 가장 적절한 에이전트로 동적으로 전달할 수 있습니다.

import { Router, Agent } from 'monan-sdk';
const fastAgent = new Agent({ model: "gemma3:4b" }); // 빠르고 저렴함
const smartAgent = new Agent({ model: "openai/gpt-5.2-pro" }); // 똑똑하고 비쌈
...

라우터를 에이전트(agent)와 동일하게 실행하세요:

monan run mainRouter:src.router

Monan은 강력한 오픈 소스 (Open Source) 오케스트레이션 (orchestration) 엔진을 특징으로 합니다. 에이전트들을 체이닝 (chaining)하고, 작업을 병렬로 실행하며, 커스텀 도구 (custom tools)를 통합할 수 있습니다.

import { Agent, Workflow } from 'monan-sdk';
import { tool } from 'monan/tools';
// --- 도구 (Tools) ---
...

워크플로 (workflow)를 실행하려면:

monan run blogFlow:src.agent

Monan은 Zod를 사용한 자동 검증을 통해 타입 안전 (type-safe) 및 자가 문서화 (self-documenting) 도구 시스템을 제공합니다. 도구는 속성 (properties)으로 정의되며 에이전트 컨텍스트 (agent context)에 자동으로 통합됩니다.

도구를 만드는 가장 간단한 방법은 클래스 내의 속성으로 정의하는 것입니다:

import { tool, extractTools } from 'monan-sdk';
import { z } from 'zod';
class WeatherTools {
...

추출된 도구는 에이전트와 원활하게 통합됩니다:

import { Agent } from 'monan-sdk';
const weatherAgent = new Agent({
name: "WeatherBot",
...

이제 에이전트는 모든 도구에 접근할 수 있으며, 사용자 질의 (user queries)를 기반으로 도구를 언제 사용할지 지능적으로 결정합니다.

import { tool, extractTools } from 'monan-sdk';
import { z } from 'zod';
class CalculatorTools {
...

✅ 타입 안전 입력 (Type-Safe Inputs): 자동 Zod 검증을 통해 올바른 입력 타입을 보장합니다.

✅ 자가 문서화 (Self-Documenting): 설명과 스키마 (schemas)가 LLM에 자동으로 노출됩니다.

✅ 에러 핸들링 (Error Handling): 상세한 검증 메시지와 함께 우아하게 실패를 처리합니다.

✅ 성능 (Performance): 오버헤드 없이 Bun 런타임 (runtime)에 최적화되어 있습니다.

✅ 조합 가능성 (Composable): 깔끔한 조직화를 위해 에이전트당 여러 개의 도구 클래스를 사용할 수 있습니다.

✅ 비동기 지원 (Async Support): 모든 도구는 API 호출 및 I/O를 위해 async/await를 지원합니다.

모든 도구 입력은 실행 전에 Zod 스키마에 따라 자동으로 검증됩니다. 잘못된 입력은 사용자의 코드에 도달하지 않습니다:

class DataTools {
fetchUser = tool({
name: 'fetchUser',
...

검증 예시 (Validation Example):

// ✅ 유효한 호출 - 완벽하게 작동함
await userTool.execute({ userId: "550e8400-e29b-41d4-a716-446655440000" });
// ❌ 유효하지 않은 호출 - 도움이 되는 메시지와 함께 검증 에러 발생
...

외부 API와 통합하는 실용적인 예시는 다음과 같습니다:

import { tool, extractTools } from 'monan-sdk';
import { z } from 'zod';
class ApiTools {
...

기본적인 타입 체크를 넘어 커스텀 검증 로직 (validation logic)을 추가하세요:

import { tool } from 'monan-sdk';
import { z } from 'zod';
class AdvancedTools {
...

도메인별로 도구 (tools)를 조직화하고 단일 에이전트 (agent)에 결합하세요:

import { tool, extractTools } from 'monan-sdk';
class DatabaseTools {
query = tool({
...

1. 명확한 설명 (Clear Descriptions)

// ❌ 나쁨 - 모호한 설명
const badTool = tool({
description: "무언가를 수행합니다",
...

2. 스키마 (Schemas) 내 서술적인 필드 이름

// ✅ 좋음 - LLM이 문맥을 이해함
inputSchema: z.object({
sourceAccountId: z.string().describe("송신자의 계정 ID"),
...

3. 적절한 에러 핸들링 (Error Handling)

fetchData = tool({
description: "외부 API에서 데이터를 가져옵니다",
inputSchema: z.object({ url: z.string().url() }),
...

4. 도구의 역할 집중 (Keep Tools Focused)

// ❌ 나쁨 - 너무 많은 책임
extractData = tool({
description: "데이터를 추출, 변환, 검증 및 저장합니다",
...

매우 복잡한 작업의 경우, HyperAgent를 사용하세요. 단순한 라우터 (Router)와 달리, HyperAgent는 계획을 세우고, 작업을 세분화하며, 전문화된 에이전트 팀을 관리하여 작업을 실행하고 최종 결과를 합성 (synthesizing)합니다.

이는 Plan-Delegate-Synthesize 패턴을 자동으로 구현합니다.

import { Agent, HyperAgent } from 'monan-sdk';
import { extractTools } from 'monan-sdk';
// 도구가 임포트되었다고 가정합니다...
...

실행하기:

monan run techLead:src.agent

시나리오:

사용자: "yahoo-finance API를 사용하여 Apple의 최신 주가를 가져오는 Python 스크립트를 작성해줘. 하지만 먼저 API 문서를 확인해서 올바른 엔드포인트 (endpoint)를 찾아줘." -
HyperAgent 로직:-
WebResearcher 호출: "주가를 위한 yahoo-finance API 문서를 찾아줘." -
문서 정보 수신. -
SeniorDev 호출: "이 엔드포인트 [url]를 사용하여 Python 스크립트를 작성해줘..." -
출력: 사용자에게 코드를 반환합니다.

Monan은 Hugging Face 모델과 함께 bun:sqlite의 네이티브 최적화 (native optimization)를 사용하여 즉각적인 RAG (Retrieval-Augmented Generation)를 생성합니다.

import { LocalEmbeddings } from 'monan/embeddings';
import { SQLiteVectorStore } from 'monan/memory';
const embedder = new LocalEmbeddings({ model: "BAAI/bge-large-en-v1.5" });
...

CLI는 Monan의 핵심입니다:

monan init <project-name>
: 보일러플레이트 (boilerplate) 구조를 가진 새 프로젝트를 생성합니다.

monan test <agent-var-name>:<file>
: 디버깅을 위해 터미널에서 에이전트/워크플로우 (agent/workflow)를 실행합니다.

monan run <agent-var-name>:<file>
: 프로덕션 서버 (Elysia API)를 구동합니다.

monan save <agent-var-name>:<file>
: UI를 위해 에이전트를 인덱싱 (indexing) 합니다.

우리는 강력한 도구는 접근 가능해야 한다고 믿습니다. 이제 UI가 커뮤니티 플랜 (Community Plan)에 포함되었습니다.

기능	커뮤니티 (무료)	엔터프라이즈 (Enterprise)
프레임워크 SDK (오픈 소스)	✅	✅
CLI & 로컬 추론 (Local Inference)	✅	✅
Monan UI (시각적 인터페이스)	✅	✅
OpenRouter 통합	✅	✅
워크플로우 오케스트레이션 (Workflow Orchestration)	✅	✅
KPI 및 메트릭 대시보드	❌	✅
감사 로그 (Audit Logs, 컴플라이언스)	❌	✅
SSO & RBAC	❌	✅
우선 지원 (Priority Support)	❌	✅

커뮤니티 플랜: 에이전트를 로컬에서 구축, 배포 및 시각화하는 데 필요한 모든 것을 포함합니다.
엔터프라이즈 플랜: 거버넌스 (governance), 상세 메트릭 및 SLA 지원이 필요한 기업을 위해 설계되었습니다.

우리는 JavaScript/Bun 환경에서 로컬 AI (Local AI)의 미래를 구축하고 있습니다. Monan의 성능이 마음에 드신다면:

• 이 저장소에 Star ⭐️를 눌러주세요 (100개 스타 달성을 도와주세요!).
• 제안 사항이 있다면 Issue를 열어주세요.
• Monan을 어떻게 사용하고 있는지 토론 (discussions)에서 댓글을 남겨주세요.

Bun을 사용하여 ❤️로 제작되었습니다.