Bash4LLM+ 개요: LLM API용 경량 Bash 래퍼

Bash4LLM+ 개요: LLM API용 경량 Bash 래퍼

Bash4LLM+는 Groq의 OpenAI 호환 API 및 기타 LLM 제공자와 인터페이스하도록 설계된 경량, 의존성 없는 Bash 래퍼입니다. 보안과 이식성을 우선시하는 단일 감사 가능한 Bash 스크립트를 사용하여 명령줄에서 직접 대형 언어 모델과 상호 작용할 수 있습니다.

핵심 기능 및 아키텍처

Bash4LLM+는 표준 Unix 유틸리티(bash, coreutils, findutils, util-linux, gawk, curl, jq)만 필요로 하는 자체 포함 스크립트로 동작합니다. Linux, macOS, WSL, Cygwin, BSD 및 Android의 Termux와 호환되도록 설계되었습니다.

설계상의 보안

도구는 단일 사용자 환경에서 안전하도록 여러 보안 조치를 구현합니다:

  • eval 또는 /tmp 사용 금지: 스크립트는 eval 사용을 피하고 공용 시스템 /tmp 디렉터리를 사용하지 않아 일반적인 쉘 취약점을 방지합니다.
  • 격리된 임시 파일: 임시 파일은 제한된 권한(umask 077)을 가진 사용자 정의 $RUN_TMPDIR에 저장됩니다.
  • 출력 안전성: 스크립트는 LLM으로부터 받은 출력을 절대 실행하지 않습니다.
  • 권한 제어: 파일은 600 권한으로 저장되어 프라이버시를 보장합니다.

UI 상태 시스템 (ui_state)

Bash4LLM+의 차별화된 기능 중 하나는 ui_state 시스템입니다. 핵심 스크립트는 $BASH4LLM_CONFIG_DIR/ui_state에 원자적 JSON 파일 형태로 운영 메타데이터를 노출합니다. 이를 통해 외부 GUI나 도구(예: Home Assistant)가 원시 로그를 파싱할 필요 없이 CLI와 통합할 수 있습니다. 시스템은 다음을 추적합니다:

  • 세션 상태: 활성 세션, 메시지 수, 타임스탬프.
  • API 결과: HTTP 상태, 요청 ID, 감지된 엣지 케이스.
  • 제공자 기능: 활성 제공자가 스트리밍 또는 모델 새로 고침을 지원하는지 여부.

세션 관리 및 컨텍스트 메모리

Bash4LLM+는 기본적으로 메모리를 유지하지 않습니다. 컨텍스트 메모리는 사용자가 --session <id> 플래그를 명시적으로 사용하여 세션을 시작할 때만 활성화됩니다.

지속적 히스토리

세션이 활성화되면 도구는 $BASH4LLM_HISTORY_DIR/sessions/<session_id>.ndjson에 지속적인 NDJSON 파일을 생성합니다. 이 파일은 대화 히스토리를 저장하며, API에 컨텍스트를 유지하기 위해 다시 전송됩니다. 사용자는 --session-window [n] 플래그를 사용해 전송되는 컨텍스트 양을 제어할 수 있으며, 기본값은 10개의 메시지입니다.

운영 사용법 및 명령 인터페이스

기본 상호 작용

사용자는 여러 방법으로 프롬프트를 보낼 수 있습니다:

  • 직접 프롬프트: ./bash4llm "prompt text"
  • 파이프 입력: echo "prompt" | ./bash4llm
  • 파일 입력: ./bash4llm -f prompt.txt
  • 다중 라인 입력: 히어도크(<<'EOF') 사용.

모델 및 제공자 관리

Bash4LLM+는 하드코딩된 모델을 피하고 제공자의 API(예: GET https://api.groq.com/openai/v1/models)를 통해 사용 가능한 모델 목록을 동적으로 가져옵니다.

  • --refresh-models: 로컬 모델 화이트리스트를 업데이트합니다.
  • -m <model>: 단일 실행에 사용할 모델을 지정합니다.
  • --set-default <model>: 활성 제공자에 대한 지속적인 기본 모델을 설정합니다.
  • --provider <name>: LLM 제공자를 전환합니다(--install-extras 명령을 통해 Gemini, Hugging Face, Mistral 등 추가 제공자를 설치할 수 있음).

출력 옵션

사용자는 응답 수신 방식을 맞춤 설정할 수 있습니다:

  • 스트리밍: --stream 플래그는 실시간 비동기 출력을 활성화합니다.
  • JSON 출력: --json 또는 --pretty 플래그는 API의 원시 또는 포맷된 JSON 응답을 반환합니다.
  • 자동 저장: 스크립트는 구성 가능한 바이트 임계값(기본 1000바이트)을 초과하는 출력은 자동으로 저장합니다.

기술 요구 사항 및 설치

Bash4LLM+를 실행하려면 사용자의 PATH에 bash, coreutils, findutils, util-linux, gawk, curl, jq가 설치되어 있어야 합니다.

설치는 저장소를 클론하고 bin/bash4llm 스크립트를 실행 가능하게 만든 뒤 필요한 API 키를 내보내는 과정(export GROQ_API_KEY="your_key")을 포함합니다. ./bash4llm --install-extras 명령을 사용하면 추가 제공자와 템플릿을 포함한 선택적 확장 기능을 설치할 수 있습니다.

Sources