lcc — Local Context Compiler

모델에 전송할 내용을 줄이세요. 잘라낸 바이트 하나도 놓치지 마세요. 영수증을 받으세요.

Python

CI

MIT

GitHub stars

lcc는 모델 호출을 위해 텍스트를 준비합니다: 중복 및 상투적인 내용을 정리하고, 명시적인 목적에 맞는 컨텍스트를 선택하며, 무엇이 유지되었는지, 잘려나갔는지 또는 생략되었는지를 기록합니다. 선택된 내용은 있는 그대로 유지되며 (LLM 재작성 없음), 기본 경로는 API 키 없이 오프라인으로 실행되고, 모든 과정은 감사할 수 있는 JSON 보고서를 작성합니다.

세션 행은 Jev judge를 사용한 도구 호출 모드를 이용하며; 소스, 명령어 및 제한 사항은 실제 세션 측정에 있습니다. 데모 행은 GIF의 명령어로 재현 가능합니다 (정확한 tiktoken 카운트). 귀하의 축소율은 컨텍스트 중 실제로 노이즈가 얼마나 되는지에 달려 있으며; 25% 미만의 이득이라면, lcc는 가치가 없다고 알려줍니다.

빠른 시작

pip install "local-context-compiler[tiktoken]"   # CLI는 `lcc`

lcc compact notes.md -q "what is wrong with the booking flow?" \
...

모든 MCP 클라이언트 (Claude Code, Cursor, Claude Desktop 등)에서 사용하세요:

{"mcpServers": {"lcc": {"command": "lcc", "args": ["mcp"]}}}

또는 Claude Code의 손실성 /compact 요약 대신 있는 그대로의 도구 호출 압축을 대체하세요:

claude plugin marketplace add lucasmartins-ai/lcc
claude plugin install lcc@lcc

플러그인은 early-access function-hooks 플래그와 judge(Jev용 TypeSafe 키 또는 완전히 로컬인 경우 provider: laya)가 필요합니다. 이것이 없으면 내장 요약 기능으로 폴백됩니다. Claude Code plugin guide를 참조하세요.

토큰 절약 스택에서 위치

하지 않는 것

구조적인 PASS는 모델이 올바르게 답변할 것이라는 것을 보장하지 않습니다. 청소 및 프롬프트 템플릿은 별개의 변환이며, 압축 과정에서 누락 마커가 추가될 수 있습니다. 기본 오프라인 워크플로는 어휘적 점수(lexical scoring)와 구조적 검사를 사용합니다. 선택적 의미론적 프로바이더는 로컬(Laya) 또는 원격(Jev)에서 실행됩니다. RAG, 임베딩 또는 벡터 스토어는 구현되지 않았습니다.

프로젝트 상태

체크아웃은 Python 및 Node 패키지 버전 1.0.0과 Python **3.11+**를 선언하며, MSI 스프린트 1–10은 PASS 보고서가 있습니다. 연구 릴리스는 완료되었습니다. 이 소프트웨어는 패키지 메타데이터에서 Beta로 분류됩니다.

⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.

[번역된 제목]: lcc — 로컬 컨텍스트 컴파일러 (Local Context Compiler)

[본문]
The 2026-10-03 감사에서 발견된 R1–R3 사항은 Sprint 10에서 해결되었습니다: 모든 시도 비용 회계(all-attempt cost accounting), 공유 페어드 부트스트랩(shared paired bootstrap), 그리고 전체 페이로드 드리프트 검사(full-payload drift checks)가 MSI-Bench에 활성화되었습니다. 동결된 계약서(Frozen contracts), 아키텍처 논문, 선행 기술 검토, 제한 사항 및 연구 의제, 버전 매니페스트, 그리고 마스터 결과가 게시되었습니다.

소스에서 설치하기

로컬 체크아웃(local checkout)의 경우:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install .
...

런타임 종속성(Runtime dependencies)은 Typer, Rich, 그리고 PyYAML입니다. 이 경로는 모델이나 API 키가 필요하지 않습니다. 설치 과정에서 Python 종속성이 다운로드될 수 있으며, 아래 워크플로우는 오프라인으로 실행됩니다. 레지스트리 패키지를 설치하려면 pip install local-context-compiler를 사용하십시오. 그 내용은 현재 체크아웃 내용과 다를 수 있습니다. 실행 파일은 lcc입니다. 이름이 같은 PyPI 패키지 lcc는 이 프로젝트와 무관합니다.

선택적 추가 기능(Optional extras):

python -m pip install '.[tiktoken]'  # 에셋 인코딩 시 정확한 카운트가 필요할 때
python -m pip install '.[laya]'      # 로컬 의미론적 제공자; 스테이지 모델 종속성

Tiktoken은 캐시된 인코딩 에셋 없이도 추정치를 산출할 수 있습니다. 보고서에서 token_count_method, tokenizer_id, 그리고 is_estimate를 읽고, 지원되는 명령어에 --require-exact-tokens를 사용하여 추정 카운트를 거부하십시오. 토크나이저 경계를 참조하십시오.

복사 가능한 오프라인 워크플로우

CLI를 호출하기 전에 입력을 생성합니다:

cat > dossier.md <<'EOF'
The mobile booking form erased patient input at step two.

...

optimize는 보일러플레이트/중복을 제거하고 프롬프트를 형식화합니다. inspect는 소스를 수정하지 않고 읽습니다. compact는 목표에 맞는 컨텍스트를 선택하며, 짧거나 보호된 입력은 변경되지 않을 수 있습니다. explain은 점수를 다시 매기지 않고 보고서를 감사(audit)합니다. diff는 비교 내용을 출력하고 파일이 다르더라도 0으로 종료됩니다. 사용자 요약은 stderr로 전송되며, 요청된 텍스트/JSON 파일에는 기계가 읽을 수 있는 출력이 담깁니다. quickstart를 참조하세요.

Python: 감사 영수증과 함께 컨텍스트 컴파일하기

from pathlib import Path
from lcc.msi import compile

...

compile()은 planner-1.0을 사용하며, 기계적 압축(mechanical compaction) 및 제한된 구조 복원(bounded structural restoration)을 수행합니다. 이는 **추론 호출(inference call)**을 하지 않습니다. 그 계획은 경로를 설명할 뿐이며, 해당 모델을 실행하지는 않습니다. 이 래퍼는 위험도를 low로 고정하므로, 더 높은 위험도의 작업을 위해서는 planner API를 명시적으로 사용하세요. 영수증의 제로 API 비용은 원격 호출이 없음을 의미하며, CPU 및 에너지 소비만 제외합니다.

동일한 입력은 동일한 컨텍스트 바이트를 생성하지만, 영수증 시계(receipt clocks)는 다를 수 있습니다. 빈 작업/컨텍스트와 음의 복원 예산은 ValueError를 발생시킵니다. API 계약에는 msi-api-1.0과 그 제한 사항이 문서화되어 있습니다. 전체 실행/검증 체인(verification chains)을 위해서는 별도의 verification 및 escalation API를 사용하세요.

제공업체와 실패 처리

| Provider | Execution | Setup | What the report establishes |
| :--- | :--- | :--- |
| mechanical | 오프라인 어휘 점수화 (Offline lexical scoring) | 기본 설치 (Base install) | semantic_guarantee: none; 의미론적 판단 없음 (no semantic judgment) |
| ... |

lcc compact dossier.md -q 'reduce mobile booking friction' --provider jev \
  -o compacted.md -r report.json

Jev의 선택적 경로는 요약본을 생성하는 대신 유형화된 관련성 질문을 평가합니다. 이 결정이 다운스트림 답변 품질을 보장하지는 않습니다. 제한 사항 및 폴백 계약은 Jev와 Laya를 참조하십시오. LCC_DISABLE_NETWORK=1은 Jev 경로를 비활성화합니다. 명시적으로 사용 불가능한 Jev는 컨텍스트를 유지하고 저하를 보고하며, 사용 불가능한 Laya는 이름이 지정된 기계적 폴백을 사용합니다. LCC_REQUEST_LOG=1은 ./.lcc/request-log에 (컨텍스트가 아닌) 마스킹된 목표 문자열의 로컬 로그를 활성화합니다 (LCC_REQUEST_LOG_DIR로 이동 가능); 기본값은 꺼져 있습니다. lcc request-log는 항목 수를 세고 --delete ID는 하나를 제거합니다. 출력을 사용하기 전에 provider_used, degraded, degradation_reason, 충분성 실패 및 검토 플래그를 확인하십시오.

compact는 relevance-compaction-1.2 보고서를 작성합니다. 선택적 IR은 context-ir/0.1이며, Python MSI 영수증은 inference-receipt/0.1입니다. 필드를 해석하기 전에 아티팩트의 버전을 읽으십시오.

파이프라인은 선택(selection), 결정론적 보호(deterministic protection), 유한 복원(bounded restoration) 및 구조적 검사(structural checks)를 적용합니다. 선택적 의미론적 검증(semantic verification)은 별도의 단일 패스입니다. 안전 모델, IR 및 복원 제한은 증거가 여전히 손실될 수 있는 지점을 설명합니다. 보존이 보안 판결을 의미하지는 않습니다.

에이전트, MCP 및 노드

{"mcpServers": {"lcc": {"command": "lcc", "args": ["mcp"]}}}

stdio MCP 서버는 compact, compact_transcript, inspect, prepare, explain 및 intake를 노출합니다. compact는 기본적으로 기계적 점수 산정(mechanical scoring)을 사용합니다. 도구 호출 트랜스크립트는 시맨틱 제공자(semantic provider, Jev 또는 Laya)나 오프라인 rules 정책을 사용하며, 사용자/어시스턴트 메시지는 고정(pinned) 상태로 유지됩니다. 실제 에이전트 세션의 결과는 real-session benchmarks를 참조하십시오. MCP, tool-call mode, 그리고 Claude Code integration도 참고하십시오. 플러그인 전송(Plugin transport) 및 실시간 모델 실행은 오프라인 사용성 벤치마크에서 테스트되지 않았습니다.

Node API는 결정론적 정리(deterministic cleaning), 프롬프트 템플릿, 그리고 intake를 지원하지만, Python MSI/IR/planner의 동등성은 없습니다. Node 토큰 개수는 휴리스틱(heuristic)입니다. 이 체크아웃을 사용하십시오:

const { LccCompressor } = require('./index.js');
const result = new LccCompressor().compress('context text');
console.log(result.compressedText);

agent와 route는 구성된 백엔드가 필요한 별도의 선택적 실행 경로입니다. semantic-retrieval은 비활성화/차단 경계(disabled/blocked boundary)를 보고하며, 검색 어댑터(retrieval adapter)가 구현되지 않았습니다. 명령어 요구 사항은 quickstart matrix에 나열되어 있습니다.

증거 및 사용성 (Evidence and usability)

workflow benchmark는 새 베이스 전용 venv에 휠(wheel)을 설치하고 소스 디렉토리 외부에서 실행됩니다. macOS ARM64, Python 3.12.14, 코드 커밋 310ab9e 기준:

시간에는 프로세스 시작 시간이 포함됩니다. 이것은 인간의 사용성 점수나 다른 기계에 대한 보증이 아닌, 실행 가능한 워크플로우 커버리지입니다. 전체 stdout/stderr, 패키지 버전, 입력/러너/휠 해시 및 명령어는 results.json에서 확인할 수 있습니다.

기존의 품질 증거는 별도로 보고됩니다:

출처, 정확한 커밋, 재현 및 모든 실패 사항은 실제 환경 통합 (real-world integration)을 참고하세요.
오라클 암은 lcc.msi.compile이 아닙니다. 위에 제시된 어떤 결과도 라이브 에이전트 성공, 추론 지연 시간, 실제 청구 절감액 또는 프로덕션 이전을 입증하지 않습니다.

sprint-7 파일럿 (sprint-7 pilot)에는 12개의 구성된 작업과 72개 암 실행이 포함되어 있습니다. Sprint 10에서는 감사 결과 R1–R3가 해결되었습니다: 전체 체인 시도 비용이 계산되었고, 부트스트랩 샘플링은 암별로 쌍을 이루었으며, --check는 완전한 페이로드 안정성을 단언합니다. 역사적인 의미론적 제공자 실험은 연구 현황 (research status), 전사 A/B (transcript A/B) 및 실제 세션 측정값 (real-session measurements)에 있습니다. 이 감사에서는 라이브 제공자를 사용하여 재실행되지 않았습니다.