MuzeAnisichael/minimal-local-agent: 작고 로컬 우선의 에이전트 커널

작은 로컬 우선(local-first) 에이전트 커널. 경계가 지정된 도구(Bounded tools). 되돌릴 수 있는 편집(Reversible edits). 감사 가능한 실행(Auditable runs).

간체 중국어 · Documentation · Quick start · Customize · Releases · Contribute

하나의 모델/도구 루프, 하나의 경계가 지정된 작업 공간(bounded workspace), 그리고 발생한 내용을 기록하는 로컬 SQLite 레코드를 사용합니다. CLI, 로컬 웹 콘솔 또는 자체 Python 호스트에서 Ollama나 명시적으로 구성된 Chat Completions-compatible API를 사용하세요.

범용적인 기본 도구 컬렉션을 가진 비서가 아니라, 에이전트를 이해하고 임베드하며 사용자 정의하려는 개발자를 위해 구축되었습니다.

실제 v1.0 인터페이스는 폐기 가능한 샘플 파일과 라이브 모델을 갖추고 있습니다. 웹 UI는 현재 중국어입니다. 스크린샷 출처 및 재현.

파일을 쓰지 않는 편집 미리보기 보기

모델은 실제 편집 도구를 호출했고, 샘플 파일은 변경되지 않았습니다. 웹 작업(Web tasks)은 읽거나 미리 볼 수 있습니다. 실제 쓰기 작업을 승인하려면 대화형 CLI가 필요합니다.

도구 표면을 변경하는 권한. 거부된 도구는 모델의 스키마에서 사라지며, 사용을 단념시키기 위해 프롬프트를 의존하지 않습니다.검토 가능하고 되돌릴 수 있는 편집. 하나의 경계가 지정된 diff, 하나의 승인, 오래된 파일 확인(stale-file checks), 트랜잭션 롤백(transaction rollback), 그리고 해시 검사 취소(hash-checked undo).검사 가능한 실행. 로컬 기록, 도구 감사(tool audit), 런타임 이벤트, 그리고 해시 체이닝 영수증(hash-chained receipts)이 무엇이 실행되었고 무엇이 변경되었는지 설명합니다.작은 확장 지점. 검토된 읽기 도구를 추가하거나, 모델 구성을 대체하거나, 루프를 편집하지 않고 명시적으로 컨텍스트 리듀서(context reducer)를 공급할 수 있습니다.

트레이드오프에 대한 범위 비교를 확인하세요. 이것은 Python 샌드박스도 아니며 일반적인 자율 비서도 아닙니다.

Python 3.11 이상과 도구 호출을 지원하는 모델이 필요합니다. 예제는 Ollama를 사용하며, 다른 로컬 서버 및 호환 API는 로컬 구성을 사용합니다.

git clone https://github.com/MuzeAnisichael/minimal-local-agent.git
cd minimal-local-agent
python3.11 -m venv .venv
...

Windows PowerShell

git clone https://github.com/MuzeAnisichael/minimal-local-agent.git
Set-Location minimal-local-agent
py -3.11 -m venv .venv
...

Open http://127.0.0.1:8765

. 에이전트가 접근할 수 있는 파일만 workspace/ 아래에 배치하세요.

. 터미널을 선호하시나요? minimal-agent chat을 실행하거나
minimal-agent run --read-only "List the workspace files"를 실행하세요.

.

임시 샘플 파일을 사용하여 웹 인터페이스를 사용하려면, minimal-agent web 대신 소스 체크아웃에서 다음을 실행하세요:

python examples/web_demo.py

데모가 출력하는 URL을 사용하세요. 이 기능은 설정된 실제 모델을 사용하지만 개인 작업 공간이나 저장된 세션을 절대 로드하지 않습니다. 모델 호출 시 비용이 발생할 수 있습니다.

고정 설치를 위해서는 v1.0.0 릴리스에서 wheel 파일을 다운로드하여 가상 환경에 설치하세요:

python -m pip install minimal_local_agent-1.0.0-py3-none-any.whl

PyPI 배포는 가정하지 않습니다. v1.0.0 태그는 원래 릴리스를 고정하며, 스크린샷 데모와 업데이트된 문서는 main 브랜치에서 라이브입니다.
. 더 많은 명령어 및 구성: 사용자 가이드(user guide).

from dataclasses import replace
from minimal_local_agent import AgentRuntime, Settings
runtime = AgentRuntime(replace(Settings.load("agent.toml")), write_policy="deny")
...

읽기 도구 추가 (Add a read tool): ReadTool을 명시적으로 등록하세요.
; 실행 가능한 예제부터 시작하세요.모델 선택 (Choose a model): 무시된 로컬 설정(ignored local settings)을 사용하거나 ModelFactory를 제공하세요.컨텍스트 축소 (Reduce context): 신뢰할 수 있는 context_reducer를 명시적으로 전달하세요.
; 자동 압축은 비활성화되며, 원래 기록이 저장됩니다.MCP 연결 (Connect MCP): 선택적으로 확장 기능(extra)을 설치하고 승인된 로컬 읽기 도구 목록(allowlist reviewed local read tools)을 허용하세요. 암묵적 검색이나 원격 MCP는 없습니다.

통합을 구축하기 전에 임베딩 가이드와 v1 호환성 계약(v1 compatibility contract)을 읽으세요.

flowchart LR
Host["CLI / local Web / Python"] --> Runtime["AgentRuntime: policy + budgets"]
Runtime <--> Model["Ollama / compatible API"]
...

PydanticAI가 모델/도구 반복(iteration)을 처리하며, 프로젝트 코드는 경계(boundaries), 트랜잭션 및 로컬 상태를 처리합니다. 웹 UI는 표준 라이브러리 HTTP와 순수 HTML/CSS/JavaScript만을 사용하며, 프론트엔드 빌드 스택은 없습니다. 아키텍처 및 소스 맵을 확인하세요.

v1.0 검증 기록에는 91개의 통과한 자동화 테스트와 Linux/Windows 초기 설치, 최소 지원 의존성(dependencies), 선택적 MCP를 포함하여 6개의 통과한 CI 작업이 문서화되어 있습니다.

이 열 가지 고정 예산 케이스는 모델 순위나 통계적 신뢰성 보증이 아닌 회귀(regression) 증거입니다. 누락된 사용은 알 수 없으며, 토큰 수는 금전적 비용이 아닙니다. 검토된 릴리스 결과입니다.

• 공유 작업 공간/데이터베이스당 하나의 활성 작업만 허용됩니다. 웹에서 중복 발생 시 HTTP 409를 반환합니다.
• 원격 모델 서비스는 프롬프트와 도구 결과를 받습니다. 개인 URL, 키 및 기본 모델은 무시되는 로컬 구성 또는 환경에만 속해야 합니다.
• 기록(History)과 되돌리기 스냅샷(undo snapshots)에는 파일 텍스트가 포함될 수 있습니다. 지원되는 업그레이드 전에 SQLite 데이터베이스를 보호하고 백업하세요.
• Python 읽기 도구와 MCP 허용 목록은 샌드박스가 아닌 신뢰할 수 있는 선언입니다. 영수증 재작성 감지(Receipt rewrite detection)에는 SQLite 외부에 보관된 최종 해시가 필요합니다.
• 내장 셸, 삭제, 브라우저 제어, 의미론적 메모리(semantic memory), 스케줄링, 숨겨진 에이전트 또는 일반적인 충돌 복구 오케스트레이션 기능은 없습니다.

보안 정책 · 문제 해결 (Troubleshooting) · 유지보수 로드맵

작은 수정 사항, 테스트, 예제 및 문서는 환영합니다. 버그를 보고하거나 개선 사항을 제안한 후 기여 가이드(contribution guide)를 따르세요. 독립적으로 검증 가능한 변경 사항을 작은 커밋으로 유지하고 커널의 좁은 범위를 보존하세요.