AMBER ICI v5: 사건 범위 증거, 에이전트 체인, 하이브리드 검색, 스트리밍 분석, 그래프 및 타임라인 뷰, OCR, 통제된 웹 조사, GPU 텔레메트리를 갖춘 로컬 우선 Ollama 수사 지휘 센터입니다.
<p align="center"> <img src="https://assets.kitploit.com/production/public/readmes/12061/b3526255ef1a43950d559d01043863d61c0ef36cfbf4e3270caef742cde07d9e.png" alt="AMBER ICI 인터페이스 배너" width="1200" /> </p> # AMBER ICI v5 AMBER ICI(AMBER Investigative Command Interface)는 로컬 [Ollama](https://ollama.com/) 서버로 구동되는 조사 및 분석 워크플로를 위한 로컬 우선 브라우저 인터페이스입니다. 포함된 기능: - 단일 모델 Analyst Console 및 다중 모델 Parallel 실행 - 메인 터미널의 `SEND` 버튼으로 구동되는 사용자 정의 에이전트 체인 - 어떤 에이전트가 실행되는지, 몇 개가 실행되는지, 몇 번 반복되는지, 각 에이전트가 어떤 로컬 모델을 사용하는지에 대한 사용자 제어 - 평이한 언어로 된 목표로부터 에이전트 구성을 로컬 모델로 생성 - Ollama 임베딩으로 뒷받침되는 영구 시맨틱 Archive - 활성 파일 컨텍스트를 위한 피보나치 프랙탈 검색 - 파일 업로드, 읽기 전용 연결 디렉터리 접근, 텍스트 추출 및 OCR - 단일 마스터 스위치 뒤에 있는 선택적 Playwright 기반 웹 가져오기 및 공공 기록 검색 - 독립형 엔티티 그래프, 타임라인 및 벡터 저장소 뷰 - 사용 가능한 경우 로컬 토큰 속도, 세션, GPU/VRAM 및 온도 텔레메트리 Ollama 추론은 UI에 의해 루프백 엔드포인트(`127.0.0.1`, `localhost` 또는 `::1`)로 제한됩니다. AMBER는 클라우드 추론이나 애플리케이션 텔레메트리를 포함하지 않으며, 어떤 기능도 로그인, API 키 또는 계정을 요구하지 않습니다. `WEB` 필은 모든 인터넷 접근을 위한 마스터 스위치입니다. 이 필이 `OFF`인 상태에서는 AMBER가 어떤 종류의 아웃바운드 요청도 하지 않습니다. ## v5 하이라이트 - 사건 범위로 제한된 증거 및 Archive 검색을 갖춘 로컬 사건 워크스페이스 - 스트리밍 SHA-256 아티팩트 식별, 수집 출처, 중복 탐지 및 출처 인용 - 기존 시맨틱 Archive 결과와 융합된 결정적 키워드 검색 - 세션, 조사관, 사건, 에이전트 또는 추론 작업에 범위가 지정된 명시적이고 제한된 메모리 - 설치된 로컬 Ollama 모델을 사용하는 운영자 선택 조사 역할 템플릿 - 에이전트별 모델, 제한, 형식, 핸드오프 및 루프 제어를 갖춘 메인 터미널에서의 에이전트 실행 - Playwright WEB 사전 점검, 가시적 실행 진단, 직접 가져오기 폴백 및 1시간 로컬 캐싱 - Metal, CUDA, ROCm, 통합 메모리, 활용률 및 온도 보고를 갖춘 캐시된 하드웨어 탐지 - 반응형 장문 출력을 위한 병합된 스트리밍 업데이트 - 제한된 영속 메타데이터, 이스케이프된 생성 UI 콘텐츠, 재현 가능한 Node 의존성 및 확장된 민감 런타임 제외 ## 현재 기능 세트 ### Analyst Console - 선택된 하나의 Ollama 모델과 대화를 스트리밍합니다 - 시스템 프롬프트, JSON 출력 모드, 시드, 온도 및 CTX 크기를 지원합니다 - 활성 파일, 선택적 웹 및 유지된 대화 컨텍스트를 주입합니다 - `STOP` 또는 `Esc`로 활성 작업을 중지합니다 콘솔 필 바에는 실행 제어가 있습니다: | 필 | 값 | 용도 | |---|---|---| | `TEMP` / `CTX` / `MEM` / `FMT` / `STREAM` / `SEED` / `SYS` | — | Analyst 모드 추론 설정 | | `WEB` | `OFF` (기본값) / `ON` | 모든 인터넷 접근을 위한 마스터 스위치 | | `EXEC` | `ANALYST` (기본값) / `AGENTS` | `SEND`가 실행하는 것: 단일 활성 모델 또는 에이전트 체인 | | `AGN` | `0` = 전체 | 체인이 실행하는 에이전트 수, 카드 순서대로 적용 | | `LOOPS` | `1`+ | 체인이 반복되는 횟수; Agents 패널의 `LOOPS` 필드와 연동됨 | ### Parallel - 체크된 모든 모델에 대해 동일한 프롬프트를 실행합니다 - 각 응답을 독립적으로 스트리밍하고 추적합니다 - Analyst Console에서 사용하는 것과 동일한 CTX 및 활성 파일 제어를 적용합니다 ### Agents — 실행 체인 에이전트는 사용자 정의이며 기본 실행 경로입니다. 내장되거나 고정된 에이전트 목록은 없습니다. Agents 패널은 비어 있는 상태로 시작하며 두 가지 방법으로 채웁니다: - `+ CREATE AGENT` — 직접 하나를 정의합니다 - `GENERATE FROM PROMPT` — 목표를 설명하면 선택된 로컬 플래너 모델이 에이전트 세트를 작성합니다 각 에이전트는 자체 런타임 구성을 저장합니다: | 필드 | 기본값 | 비고 | |---|---|---| | 에이전트 이름 | — | 필수 | | 에이전트 목적 | — | `[AGENT PURPOSE]`로 주입됨 | | 에이전트 시스템 프롬프트 | — | 에이전트의 역할 지시 | | 선호 로컬 모델 | — | 필수; Ollama에 설치되어 있어야 함 | | Temperature | `0.35` | 에이전트별 설정, 콘솔의 `TEMP` pill과 독립적 | | 최대 출력 토큰 | `0` (자동) | `0`은 AMBER의 길이 휴리스틱을 사용 | | 루프 | `1` | 이 에이전트가 체인 루프당 수행하는 패스 수, 각 패스는 자체 이전 출력을 개선함 | | 출력 형식 | 일반 텍스트 | `JSON`은 Ollama의 JSON 모드를 설정하고 길이 확장을 건너뜀 | | 핸드오프 지시 | — | 다음 순차 에이전트에 `[HANDOFF FROM PREVIOUS AGENT]`로 전달됨 | | 실행 모드 | `sequential` | `sequential`, `parallel`, 또는 `gated` | | 출력 대상, 메모리 범위, 역할, 도구 접근, 활성화, 비고 | — | `ADVANCED` 아래에 있음 | **체인 실행.** `EXEC`를 `AGENTS`로 설정하고 메인 터미널에 프롬프트를 입력한 뒤 `SEND`를 누릅니다. AMBER는 선택된 모드, 활성화된 에이전트, 각 에이전트의 로컬 모델, `AGN` 개수, `LOOPS` 개수를 읽은 후 실행합니다: `parallel` 에이전트를 동시에 실행한 뒤, 카드 순서대로 `sequential` 에이전트를 루프당 한 번씩 실행합니다. 각 순차 에이전트는 이전 에이전트의 출력을 `[UPSTREAM OUTPUT]`으로 받고 해당 에이전트의 핸드오프 노트도 함께 받습니다. 진행 상황과 모든 에이전트의 스트리밍 출력이 메인 터미널에 출력되며, 최종 답변은 대화 기록에 보존됩니다. Agents 패널의 `RUN` 버튼은 패널 자체의 `LOOPS` 필드를 사용하여 동일한 작업을 수행합니다. `AGENTS` 모드에서 `SEND`는 Models 패널에 활성 모델이 필요하지 않습니다. 각 에이전트가 자체 모델을 갖고 있기 때문입니다. `gated` 에이전트는 체인에서 제외됩니다 — 해당 카드의 `RUN` 버튼으로 개별 실행하십시오. **누락된 모델은 절대 대체되지 않습니다.** Ollama에 없는 모델로 에이전트를 저장하거나 체인을 시작하면, 터미널에 요청된 모델, 실제로 설치된 모델, 필요한 `ollama pull <model>` 명령을 명시한 실행 가능한 안내 블록이 출력되며 실행이 시작되지 않습니다. 저장된 에이전트 세트는 Agents 패널에서 이름으로 저장하고 복원할 수 있습니다. > 이전의 `PIPELINE` / `CHAIN` 단계 순차 모드는 인터페이스에서 폐기되었습니다. 해당 엔진과 `state/pipeline_state.json`은 하위 호환성을 위해 그대로 유지되지만, 더 이상 선택 가능한 모드가 아닙니다. 에이전트가 실행 체인입니다. ### 아카이브 및 메모리 - `embeddinggemma:latest`로 파일을 청크 및 임베드 대기열에 추가 - 코사인 유사도로 로컬 아카이브 검색 - 아카이브 JSON 가져오기 및 내보내기 - 가장 최근 어시스턴트 출력을 아카이브에 직접 추가 - 파일 소스 검색을 위한 브라우저 내 피보나치 프랙탈 인덱스 구축 - `FAST`, `HYBRID`, `DEEP` 검색 프로필 제공 ### 사례 인텔리전스 아카이브에는 이제 기존의 전체 아카이브 워크플로를 대체하지 않으면서 선택적 사례 경계가 포함됩니다: - `NEW CASE`는 로컬 사례 메타데이터를 생성합니다. - `ADD ACTIVE TO CASE`는 선택된 파일을 증거로 기록하고, 기존 원본 업로드를 유지하며, 스트리밍 SHA-256 식별자를 계산하고, 수집 출처를 기록합니다. - 사례가 선택된 상태에서 인덱싱된 아카이브 벡터는 해당 사례 ID를 지닙니다. 사례 검색은 두 가지가 모두 사용 가능할 때 해당 의미론적 결과를 결정론적 키워드 폴백과 융합합니다. - `REMEMBER LAST`는 최신 어시스턴트 출력을 레이블이 지정된 사례 메모리로 명시적으로 저장합니다. 모델 출력은 증거나 메모리로 조용히 승격되지 않습니다. - `ADD INVESTIGATION ROLES`는 선택적 Director, Researcher, Investigator, Analyst, Documenter, Critic 템플릿을 기존 사용자 정의 에이전트 레지스트리에 추가합니다. 이들은 운영자가 선택한 로컬 모델을 사용하며 자동으로 실행되지 않습니다. 사례 인텔리전스는 하나의 버전 관리된 표준 라이브러리 JSON 저장소에 원자적으로 저장되며 AMBER의 기존 Ollama 클라이언트를 사용합니다. ### 독립 실행 뷰 헤더는 다음 도구들을 별도 탭에서 엽니다: - 엔티티 출처 그래프: `http://127.0.0.1:8765/amber_graph.html` - 타임라인: `http://127.0.0.1:8765/amber_timeline.html` - 벡터 저장소 관리자: `http://127.0.0.1:8765/amber_vectorstore.html` ## 요구 사항 핵심 런타임: - Python 3.10 이상; 런처와 핵심 백엔드는 표준 라이브러리만 사용하므로 AMBER를 실행하는 데 `pip install`이 필요하지 않습니다 - Ollama가 로컬에 설치되어 실행 중이어야 함 - 최소 하나의 Ollama 생성 모델 - Archive 인덱싱 및 시맨틱 검색을 위한 `embeddinggemma:latest` 선택적 기능: - JavaScript로 렌더링되는 웹 가져오기 및 레코드 검색을 위한 Node.js 18+ 및 npm, 그리고 프로젝트 의존성 - 해당 브라우저 기반 기능을 위한 Playwright Chromium 브라우저 - PDF OCR을 위한 `ocrmypdf` 및 Tesseract - 이미지 OCR을 위한 Tesseract - Tesseract가 WebP 이미지를 직접 읽을 수 없을 때 OCR 전에 변환하기 위한 Pillow - 추가 시스템 지표를 위한 `psutil`, `nvidia-smi` 또는 `osx-cpu-temp`; 사용할 수 없는 값은 그냥 비워 둡니다 위의 모든 것은 로컬에서 동작합니다. 어떤 구성 요소도 계정, API 키 또는 클라우드 서비스를 필요로 하지 않습니다. ## 설치 및 실행 ### 1. 저장소 복제 ```bash git clone https://github.com/gs-ai/AMBER-ICI.git cd AMBER-ICI ``` ### 2. Ollama 시작 별도의 터미널에서: ```bash ollama serve ``` 필요한 임베딩 모델과 최소 하나의 생성 모델을 가져오세요: ```bash ollama pull embeddinggemma:latest ollama pull qwen2.5-coder:7b ``` 생성 모델은 예시일 뿐이며, AMBER는 Ollama에서 로컬로 설치된 모델을 탐색합니다. ### 3. Python 환경 생성 핵심 백엔드는 Python 표준 라이브러리만 가져오므로, 직접 실행하는 경우 가상 환경은 선택 사항입니다. 그래도 npm 스크립트(`venv/bin/python3`를 호출함)나 선택적 Pillow 지원을 사용하려면 가상 환경을 생성하십시오: ```bash python3 -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate python3 -m pip install --upgrade pip ``` `requirements.txt`는 필요하지 않기 때문에 존재하지 않습니다. 원하는 경우에만 해당 환경에 선택적 추가 기능을 설치하세요: ```bash python3 -m pip install Pillow # optional: WebP conversion before OCR ``` `deactivate`로 비활성화합니다. 이전 AMBER 버전이 `venv/`에 사용하지 않는 패키지(예: `camoufox`)를 남겨두었다면, 해당 패키지들은 현재 코드에서 임포트되지 않으므로 무시하거나 제거해도 됩니다. ### 4. 핵심 애플리케이션 실행 ```bash python3 files/launch_amber_ici_gui.py ``` AMBER는 브라우저를 자동으로 엽니다. 탭을 열지 않고 실행하려면: ```bash python3 files/launch_amber_ici_gui.py --no-browser ``` 그런 다음 `http://127.0.0.1:8765/amber_ui.html`을 엽니다. ### 5. 선택적 브라우저 기반 웹 기능 설치 `WEB` 알약을 켤 계획인 경우에만 필요합니다: ```bash npm install # playwright, playwright-extra, stealth plugin npx playwright install chromium # the browser binary itself ``` AMBER가 실행 중인 상태에서 헬퍼가 실행 가능한지 확인합니다. 이 명령은 헬퍼 경로, 확인된 `node` 바이너리, 그리고 누락된 패키지를 보고합니다: ```bash curl -s http://127.0.0.1:8765/api/web/status ``` AMBER는 JavaScript로 렌더링되는 페이지에 Node/Chromium 헬퍼를 사용하며, 직접 URL에 대해서는 일반 Python HTTP 가져오기를 폴백으로 사용합니다. records-search 헬퍼는 Node.js, npm 의존성 및 Chromium이 필요하며, 일반 HTTP 폴백은 없습니다. ### 6. 선택적 OCR 지원 설치 Homebrew를 사용하는 macOS: ```bash brew install ocrmypdf tesseract python3 -m pip install Pillow ``` Ubuntu/Debian: ```bash sudo apt-get update sudo apt-get install -y ocrmypdf tesseract-ocr python3 -m pip install Pillow ``` Pillow는 Tesseract가 처리하기 전에 변환이 필요한 이미지 형식에만 필요합니다. 선택적 OCR 종속성이 없더라도 AMBER는 계속 실행됩니다. ### npm 편의 스크립트 제공된 npm 스크립트는 `venv/bin/python3`로 AMBER를 실행하므로, 먼저 해당 환경을 생성하세요(3단계): ```bash npm start # 127.0.0.1:8765, no browser tab npm run start:browser # same, and opens the browser ``` `python3`로 직접 실행하는 것이 가장 이식성이 뛰어난 방법입니다. ### 전체 설정, 처음부터 끝까지 ```bash git clone https://github.com/gs-ai/AMBER-ICI.git cd AMBER-ICI python3 -m venv venv # for the npm scripts npm install # optional: WEB features npx playwright install chromium # optional: WEB features ollama serve & # in its own terminal ollama pull embeddinggemma:latest # required for Archive ollama pull qwen2.5-coder:7b # any generation model npm start # → http://127.0.0.1:8765/amber_ui.html ``` ## 실행기 옵션 ```bash python3 files/launch_amber_ici_gui.py --help ``` | 플래그 | 기본값 | 용도 | |---|---:|---| | `--host HOST` | `127.0.0.1` | AMBER HTTP 서버가 수신 대기하는 주소 | | `--port PORT` | `8765` | AMBER HTTP 서버 포트 | | `--no-browser` | 꺼짐 | 기본 브라우저를 열지 않음 | | `--gui PATH` | 자동 감지 | 특정 GUI HTML 파일 제공 | | `--version` | — | AMBER ICI 릴리스 버전을 출력하고 종료 | 브라우저 UI는 AMBER 서버가 다른 인터페이스에 바인딩되어 있더라도 의도적으로 루프백 Ollama URL만 허용합니다. ## 최초 실행 워크플로 1. 오른쪽 상단의 Ollama 엔드포인트가 `http://127.0.0.1:11434`인지 확인합니다. 2. `PING`을 클릭하여 로컬에 설치된 모델을 불러옵니다. 3. Models 패널에서 모델 하나를 선택합니다. 4. Analyst Console에 프롬프트를 입력하고 `SEND`를 클릭합니다. 5. 선택적으로 파일을 업로드하거나 디렉터리를 연결한 다음, 파일을 활성화하여 컨텍스트에 포함합니다. 6. Archive에서 파일을 인덱싱하기 전에 `embeddinggemma:latest`를 풀(pull)합니다. 대신 에이전트 체인을 실행하려면: 1. 왼쪽 패널에서 `AGENTS` 탭을 엽니다. 2. `+ CREATE AGENT`로 에이전트를 생성하거나, `GENERATE FROM PROMPT`에서 목표를 설명합니다. 3. 콘솔 필 바에서 `EXEC`를 `AGENTS`로 설정합니다. 4. `AGN`(에이전트 수, `0` = 전체)과 `LOOPS`(패스 횟수)를 설정합니다. 5. 메인 터미널에 프롬프트를 입력하고 `SEND`를 누릅니다. AMBER가 인터넷을 읽도록 하려면 먼저 `WEB` 필을 `ON`으로 설정하세요. 기본값은 `OFF`입니다. ## 파일 수집 업로드는 파일당 100 MiB로 제한됩니다. 파일 선택기와 드래그 앤 드롭 경로는 현재 다음을 허용합니다: - 문서: `.txt`, `.md`, `.pdf`, `.docx`, `.rtf` - 데이터/설정: `.csv`, `.xlsx`, `.json`, `.yaml`, `.yml`, `.toml`, `.ini`, `.cfg`, `.conf`, `.xml` - 소스/로그: `.py`, `.js`, `.ts`, `.tsx`, `.jsx`, `.html`, `.sql`, `.sh`, `.bash`, `.zsh`, `.log` - 이미지: `.png`, `.jpg`, `.jpeg`, `.bmp`, `.webp`, `.tif`, `.tiff`, `.svg` 추출 동작: - 일반 텍스트, 소스, 설정, CSV, RTF 파일은 텍스트로 디코딩됩니다. - XLSX 워크시트는 Python 표준 라이브러리로 추출되며, 수식과 복잡한 서식은 보존되지 않습니다. - DOCX 텍스트는 문서 XML에서 추출되며, 복잡한 레이아웃은 보존되지 않습니다. - PDF 추출은 먼저 내장 텍스트를 시도하고, `ocrmypdf`가 설치되어 있으면 OCR도 시도하여 더 유용한 결과를 유지합니다. - 래스터 이미지는 Tesseract가 설치되어 있으면 Tesseract OCR을 사용합니다. SVG 추출은 내장된 `<text>` 및 `<tspan>` 콘텐츠를 읽습니다. 업로드된 원시 바이트는 `uploads/blobs/`에, 추출된 텍스트는 `uploads/texts/`에, 메타데이터는 `uploads/manifest.json`에 저장됩니다. ### 연결된 디렉터리 `LINK DIRECTORY`는 로컬 디렉터리 하나에서 지원되는 숨김 파일이 아닌 파일을 AMBER에 노출합니다. Files 패널은 연결된 항목을 읽기 전용으로 취급하며, 디렉터리 목록은 재귀적이지 않습니다. 선택한 경로는 `state/linked_dir_state.json`에 저장되며, 파일 콘텐츠는 원래 위치에 남아 있고 컨텍스트나 추출을 위해 요청될 때만 읽힙니다. 네이티브 폴더 선택기는 Python의 Tkinter를 사용합니다. 사용할 수 없는 경우 UI에서 경로를 수동으로 입력하라는 메시지를 표시합니다. 디렉터리 연결을 해제하면 저장된 링크가 제거되지만 소스 파일은 삭제되지 않습니다. 백엔드는 몇 가지 추가 연결 파일 형식(`.xls`, `.ods`, `.gif`, `.heic`, `.ico`, `.ppt`, `.pptx`, `.zip`)을 인식합니다. 텍스트 추출기가 없는 형식은 디코딩된 콘텐츠 대신 메타데이터 레이블을 제공합니다. 레거시 `.xls` 및 `.ods` 추출은 최선 노력 방식이며 추출을 사용할 수 없다고 보고할 수 있습니다. ## 컨텍스트 및 메모리 동작 UI의 CTX 옵션은 `2K`, `4K`, `8K`, `16K`, `32K`이며 Analyst, Parallel, Agent 호출 전반에 적용됩니다. - 추론 전에 `trimMsgsToCtx()`는 요청이 선택된 컨텍스트 예산의 약 90%(토큰당 4자로 추정)에 맞을 때까지 가장 오래된 비시스템 메시지를 제거합니다. - 활성 파일 검색은 먼저 Fibonacci 프랙탈 저장소가 채워져 있으면 이를 쿼리하고, 그렇지 않으면 평면 파일 컨텍스트 조립으로 대체합니다. - 검색은 최대 깊이 4, 빔 폭 2–4, 그리고 프로필에 따른 결과 제한을 사용합니다. - 활성 파일 컨텍스트는 메모리 프로필에 따라 상한이 정해집니다: Fast에서는 약 `CTX × 2.6`자, Hybrid에서는 `CTX × 3.2`자, Deep에서는 `CTX × 4.0`자입니다. - 크기가 큰 평면 컨텍스트는 주입 전에 키워드 중복 점수로 순위가 매겨집니다. - 스크래치패드 주입은 약 8,000–20,000자의 꼬리를 유지하며, 추가로 활성 프로필의 파일 컨텍스트 예산에 의해 제한됩니다. - 전체 메모리를 가진 에이전트는 마지막 여섯 개의 대화 메시지를 받습니다. 로컬 메모리는 스크래치패드 꼬리를 사용하며, `none`은 해당 회수를 비활성화합니다. 이는 문자 기반 가드레일이며, 정확한 토크나이저 카운트가 아닙니다. 벡터 Archive는 영구적이지만, 별도의 Fibonacci 트리는 세션 메모리입니다. 이는 현재 페이지 세션 중에 해당 파일이 인덱싱될 때 파일에 대해 구축되며, 다시 로드된 후 `state/vector_store.json`에서 자동으로 재구성되지 않습니다. 재구축될 때까지 활성 파일 컨텍스트는 평면 폴백을 사용합니다. ## 지속성 런처는 영구 애플리케이션 데이터를 원자적 임시 파일 교체를 사용하여 `state/` 아래에 JSON으로 저장합니다. 활성 SQLite 마이그레이션이나 데이터베이스 의존성은 없습니다. | 경로 | 내용 | |---|---| | `state/agents_state.json` | 각 에이전트의 모델, temperature, 토큰 제한, 루프, 형식, 핸드오프를 포함한 현재 에이전트 | | `state/agent_sets.json` | 저장된 에이전트 프리셋 | | `state/agent_run_log.json` | 마지막 100회 에이전트 실행: 에이전트, 모델, 기간, 성공 여부, 컨텍스트 | | `state/pipeline_state.json` | 폐기된 파이프라인 단계, 하위 호환성을 위해 유지됨 | | `state/chain_sets.json` | 저장된 체인 프리셋 | | `state/step_run_log.json`, `state/tool_call_log.json`, `state/tool_registry_state.json` | 단계, 도구 호출, 도구 레지스트리 기록 | | `state/chat_history.json` | 마지막 100개 대화 메시지; UI는 최신 30개를 재생 | | `state/scratch.json` | 마지막 20,000자 스크래치패드 | | `state/memory_profile.json` | Fast, Hybrid 또는 Deep 검색 선택 | | `state/vector_store.json` | Archive 청크 및 임베딩 | | `state/case_intelligence.json` | 사례 메타데이터, 증거 계약 및 출처, 제한된 명시적 메모리, 에이전트 추적 영수증; 첫 쓰기 시 생성됨 | | `state/graph_state.json`, `state/timeline_state.json` | 그래프 및 타임라인 데이터 | | `state/web_cache.json` | 1시간 TTL의 직접 웹 가져오기 결과 | | `state/linked_dir_state.json` | 현재 연결된 디렉터리 경로 | | `uploads/manifest.json` | 업로드된 파일 메타데이터 | 패널 레이아웃은 브라우저 `localStorage`에 저장되므로 브라우저 프로필에 따라 다릅니다. 런타임 전용 선택, 통계, 인메모리 프랙탈 트리는 페이지 로드 시 초기화됩니다. 상태 JSON 파일을 디코딩할 수 없는 경우, 런처는 해당 파일을 `.corrupt-<timestamp>.json` 접미사로 격리하고 빈 값을 반환하여 영향을 받은 패널이 복구될 수 있도록 합니다. ## 웹 액세스 및 네트워크 경계 `WEB` 알약은 마스터 스위치이며 기본값은 `OFF`입니다. **`WEB`이 꺼져 있으면 AMBER는 어떤 종류의 아웃바운드 요청도 하지 않습니다.** 게이트는 fetch 함수 자체 내부에서 강제되므로, 프롬프트 문구, 주입된 파일 컨텍스트, 에이전트 도구 호출(`web_fetch`, `online_records_search`)이 모두 동등하게 차단됩니다. 스위치가 꺼져 있는 동안 프롬프트가 가져오기를 요청하면, 터미널은 그 사실을 알리고 요청은 조용히 실패하는 대신 전송되지 않습니다. `WEB`이 켜져 있으면 AMBER는 먼저 헬퍼 환경을 확인하고, 사용할 헬퍼 경로를 출력한 다음, 다음 순서로 요청을 해결합니다: 1. “search foxnews.com for X”와 같은 명시적 사이트 지시 — 주제가 구체적인 경우 알려진 검색 URL을 사용하여 해당 사이트를 가져옵니다. 2. “[위치]에서 [인물]에 대한 기록 검색”과 같이 구체적으로 표현된 요청 — records 헬퍼를 호출합니다. 3. 프롬프트 또는 주입된 파일 컨텍스트에 명시된 `http://`/`https://` URL 또는 인식된 베어 도메인. 4. 그 외의 경우, 프롬프트 텍스트가 DuckDuckGo의 HTML 엔드포인트로 제출되고 결과 페이지가 가져와집니다. 4단계는 `WEB`이 켜져 있을 때 프롬프트 텍스트가 일반 검색 엔진에 도달할 수 있음을 의미합니다. 텍스트가 머신을 벗어나지 않아야 하는 프롬프트의 경우 `WEB`을 끄십시오. 모든 결과는 메인 터미널에 보고됩니다: 선택된 모드, 사용된 헬퍼 경로, 전송된 요청, 이를 처리한 엔진(`playwright`, `urllib` 또는 `cache`), 콘텐츠 크기 및 주입된 위치, 또는 누락된 종속성과 이를 해결하는 명령을 명시한 실패 블록. 직접 가져오기는 `state/web_cache.json`에 한 시간 동안 캐시됩니다. 기록 검색은 다음 소스를 조회하며, 페이지 텍스트가 대상과 요청된 위치를 모두 뒷받침하는 일치 항목만 반환합니다: `casesearch.kscourts.gov`, `doc.ks.gov/offender-search`, `kbi.ks.gov/registeredoffender`, DuckDuckGo, Brave Search. 네트워크 동작은 다음과 같습니다: - 모델 검색, 추론, 임베딩 및 모델 상태는 루프백 Ollama 엔드포인트에만 연결됩니다. - AMBER 백엔드는 구성된 AMBER 호스트/포트에서 로컬 파일과 API 라우트를 제공합니다. - `WEB`이 켜져 있으면 Playwright 웹 가져오기, 해당 Python HTTP 폴백 및 기록 검색이 사용자가 선택한 사이트, 검색 제공자 및 공공 기록 사이트로 아웃바운드 요청을 수행합니다. `WEB`이 꺼져 있으면 이들 중 어느 것도 실행되지 않습니다. - `GET /api/web/status`는 로컬 전용 사전 점검으로, 파일 시스템과 `PATH`를 검사하며 네트워크 요청을 수행하지 않습니다. - AMBER 텔레메트리 엔드포인트는 없으며, 어떤 기능도 자격 증명, 키 또는 사용 데이터를 전송하지 않습니다. 가져온 페이지는 `[WEB CONTEXT]`로 프롬프트에 주입되므로 `state/chat_history.json`에 저장되는 대화 기록의 일부가 됩니다. 출력 대상이 스크래치패드인 에이전트는 `state/scratch.json`에도 추가로 기록합니다. 라이브 웹 콘텐츠는 로컬 케이스 상태에 저장됩니다. 런처는 제한적인 Content Security Policy를 전송하고, 프레이밍을 비활성화하며, `no-referrer`를 설정하고, 민감한 브라우저 권한을 차단하며, HTTP 캐싱을 비활성화합니다. 백엔드의 `/api/task/execute` 계약은 명시적으로 호출될 때 연결된 루트 내의 파일을 나열, 읽기, 쓰기, 추가 또는 생성할 수 있습니다. 해당 루트를 벗어나는 경로, 숨겨진 경로, 알 수 없는 도구 및 명시적으로 승인되지 않은 덮어쓰기는 거부합니다. 로컬 애플리케이션이 접근하고 수정할 수 있는 가시적 콘텐츠를 가진 디렉터리만 연결하십시오. ## 텔레메트리 패널 세션 카운터는 Analyst, Parallel 및 Agent 실행 중에 업데이트되며 턴, 프롬프트/출력 토큰, 최대 토큰 속도, 평균 토큰 속도 및 실시간 토큰 속도 스파크라인을 포함합니다. VRAM/모델 상주 정보는 Ollama의 로컬 `/api/ps` 엔드포인트에서 가져옵니다. 온도/활용도 판독값은 최선 노력 방식입니다: NVIDIA는 `nvidia-smi`를 사용하고, Apple Silicon은 직접 SMC 읽기를 시도하며, Linux는 열 구역을 확인하고, 선택적 도구가 폴백을 제공합니다. ## 데이터 정리 정리 전에 AMBER를 중지하십시오. 업로드된 파일을 보존하면서 영속 상태를 재설정합니다: ```bash rm -f state/*.json ``` 업로드된 blob, 추출된 텍스트 및 해당 매니페스트를 제거합니다: ```bash rm -rf uploads/blobs uploads/texts uploads/manifest.json ``` 연결된 소스 파일은 이 명령들에 의해 절대 제거되지 않습니다. 상태 및 업로드 디렉터리는 필요에 따라 다시 생성됩니다. ## 문제 해결 ### PING이 실패하거나 모델이 나타나지 않음 - `ollama serve`가 실행 중인지 확인하세요. - UI 엔드포인트가 `http://127.0.0.1:11434`인지 확인하세요. - `ollama list`를 실행하여 최소 하나의 생성 모델이 설치되어 있는지 확인하세요. ### 아카이브 인덱싱 실패 - `ollama pull embeddinggemma:latest`를 실행하세요. - UI에 표시된 엔드포인트에서 Ollama에 접근할 수 있는지 확인하세요. - 실패한 임베딩 엔드포인트 또는 입력 청크에 대해 AMBER 이벤트 로그를 검사하세요. ### 브라우저 기반 웹 가져오기 또는 레코드 검색 실패 터미널에 정확한 문제가 표시됩니다. AMBER가 실행 중인 상태에서 환경을 직접 확인하세요: ```bash curl -s http://127.0.0.1:8765/api/web/status ``` 그런 다음 누락되었다고 보고하는 항목을 설치하십시오: ```bash npm install npx playwright install chromium ``` 직접 웹 가져오기는 여전히 일반 HTTP 폴백을 통해 성공할 수 있습니다. 레코드 검색은 Playwright가 필요하며, 소스가 마크업을 변경하거나, 인증/CAPTCHA를 요구하거나, 자동화를 차단하거나, 사용할 수 없는 경우 실패할 수 있습니다. ### 아무것도 가져오지 않고 터미널에 `WEB IS OFF`가 표시됨 `WEB` 표시가 `OFF`로 되어 있으며, 이는 설계상 모든 아웃바운드 요청을 차단합니다. 이를 `ON`으로 설정하세요. ### 에이전트가 실행되지 않음: `LOCAL MODEL NOT AVAILABLE` 에이전트가 선택한 모델이 Ollama에 설치되어 있지 않습니다. 터미널은 요청된 모델, 보유한 모델, 그리고 해결 방법을 출력합니다: ```bash ollama pull <model-name> ollama list ``` AMBER는 절대 다른 모델로 조용히 대체하지 않습니다. ### `SEND`가 회색으로 표시됨 `ANALYST` 모드에서는 Models 패널에서 정확히 하나의 모델을 선택하세요. `AGENTS` 모드에서는 최소 하나의 에이전트를 생성하세요 — 해당 모드에서는 활성 모델이 필요하지 않습니다. ### PDF 또는 이미지 텍스트가 누락됨 - `ocrmypdf`와 Tesseract를 설치하세요. - 필요한 경우 WebP 변환을 위해 Pillow를 설치하세요. - 추출이 다시 실행되도록 파일을 다시 업로드하세요. - `uploads/texts/` 아래의 해당 파일을 확인하세요. ### `npm start`가 Python을 찾을 수 없음 npm 스크립트는 `venv/bin/python3`를 기대합니다. `python3 -m venv venv`를 실행하거나, `python3 files/launch_amber_ici_gui.py`로 직접 실행하세요. ### 포트 8765가 이미 사용 중임 ```bash python3 files/launch_amber_ici_gui.py --port 8877 ``` ## 프로젝트 구조 ```text AMBER-ICI/ ├── files/ │ ├── amber_graph.html │ ├── amber_timeline.html │ ├── amber_ui.html │ ├── amber_vectorstore.html │ ├── amber_intelligence/ # Standard-library case/evidence/memory service │ ├── autogen_builder.py │ ├── constrained_executor.py │ ├── launch_amber_ici_gui.py │ ├── records_search_playwright.mjs │ └── web_fetch_playwright.mjs ├── image/README/ ├── state/ # created/populated at runtime ├── uploads/ # created/populated at runtime ├── tests/ # Case-intelligence and ICI regression tests ├── package.json ├── spec.json ├── spec.schema.json ├── README.md └── LICENSE ``` ## 라이선스 MIT. [LICENSE](https://github.com/gs-ai/amber-ici/blob/main/LICENSE)를 참조하세요.