Citrus-bit/Anaxa: 감사 가능하고 일시 중지 및 제어가 가능한 연구용 에이전트 워크스테이션

English | 中文

감사 가능하고, 일시 중지 및 제어가 가능한 연구용 에이전트 워크스테이션

문헌 검색 · 증거 매핑 · 실험 폐쇄 루프 (Closed-loop) · LaTeX/PDF 초안 작성 · 인적 검토

Anaxa는 연구 워크플로우 (Research workflow)를 위한 오픈 소스 에이전트 (Agent) 시스템입니다. 이는 일반적인 챗봇이나 관리되지 않는 논문 생성기가 아니라, 문헌 검색, 증거 감사, 실험 실행, 논문 작성, 동료 검토 (Peer review) 방식의 점검 및 최종 결과물 정리를 하나의 추적 가능한 연구 생애 주기 (Research lifecycle)로 연결합니다.

시스템의 핵심 목표는 연구 과제를 "대화 중에 임시로 텍스트를 생성하는 것"에서 "모든 단계에 출처, 결과물, 상태 및 인적 제어 지점이 존재하는" 워크스테이션으로 격상시키는 것입니다. 일반적인 채팅은 여전히 입구 역할을 하지만, 복잡한 연구 과제는 백엔드의 학술 검색, 실험, 논문 내보내기 및 연구 오케스트레이션 (Orchestration) 도구로 라우팅됩니다.

적합한 시나리오는 다음과 같습니다:

• 체계적 문헌 고찰 (Systematic review), 관련 연구 (Related work), 연구 배경 조사 및 참고 문헌 정리.
• 주장 수준 (Claim-level)의 증거 바인딩이 필요한 논문 초안, 실험 보고서 및 연구 메모.
• CS/AI, 데이터 과학, 생물 정보학 및 실증 연구에서의 재현 가능한 실험 분석.
• LaTeX 논문 번들 (Bundle), BibTeX, 인용 감사 (Citation audit) 및 PDF의 일괄 내보내기.
• 장기 과제, 단계별 연구 프로젝트 및 인적 승인이 필요한 자동화된 연구 프로세스.

Anaxa의 연구 링크는 ResearchQuest를 중심으로 전개됩니다. 이는 하나의 연구 과제를 검사 가능하고 복구 가능한 단계로 분해합니다:

intake
-> literature
-> novelty_check
...

각 단계는 입력, 출력, 도구 호출, 결과물, 실패 원인 및 게이트 (Gate) 결정을 연구 원장 (Research ledger)에 기록합니다. 외부 코드 실행, 장기 실험, 실험 코드 자동 수정 및 최종 논문 발행과 같이 리스크가 높은 단계의 경우, 시스템은 모델이 그대로 진행하도록 방치하는 대신 기본적으로 인적 확인을 요구합니다.

논문 생성은 기본적으로 "2단계" 인도 방식을 채택합니다: research_assistant action="run_pipeline"은 먼저 manuscript_draft 단계에서 편집 가능한 초안과 fast draft .tex를 반환하고 draft_ready_at을 기록합니다. 그 후 추적 가능한 백그라운드 최종화 실행 (Finalization run)을 생성하여 검토, 수정, 인용 감사 (Citation audit), 품질 감사, PDF 컴파일 및 최종 번들을 계속 완료합니다. 장 초안은 research.manuscript_section_concurrency에 따라 병렬로 생성되며, fast_draft_model / finalization_model을 통해 초안 속도와 최종 품질 모델을 구분할 수 있습니다.

academic_research는 다중 소스 문헌 검색, 메타데이터 표준화, 중복 제거, 증거 카드 생성, 참고 문헌 내보내기 및 커버리지 감사 (Coverage audit)를 담당합니다.

• Semantic Scholar, OpenAlex, Crossref, arXiv, DBLP, OpenReview, ACL Anthology 등의 소스 조합을 지원합니다.
• 참고 문헌은 사용자가 선택한 형식으로 출력할 수 있으며, APA 7, MLA 9, Chicago, GB/T 7714, plain text 및 BibTeX를 지원합니다.
• 리뷰 (Review), 서베이 (Survey), 원고 (Manuscript) 유형의 작업은 더 엄격한 품질 설정을 활성화합니다: 더 높은 레퍼런스 목표치, 본문 인용 밀도 검사, 주제 이탈 문헌 필터링 및 자동 보충 검색.

Anaxa는 "문말에 참고 문헌 목록이 있음"을 적절한 인용으로 간주하지 않습니다. 핵심 주장은 구체적인 증거에 바인딩되어야 합니다:

claim -> paper_id -> citation_key -> snippet/page/abstract evidence -> support_status -> confidence

전체 PDF가 없는 경우 시스템은 제목, 초록 및 메타데이터를 사용하는 방식으로 강등(Degrade)하여 사용하지만, 감사 (Audit) 시 이러한 증거를 약한 증거 (Weak evidence)로 표시합니다. 인용 키 (Citation key) 누락, \nocite{*} 오용, 본문 내 단락 수준 인용 부족, 지원되지 않는 주장 (Unsupported claim) 또는 저자 프로세스 설명 잔류 등은 모두 citation_audit.json에 노출되며 최종 PDF 발행을 차단할 수 있습니다.

experiment_lab

• Python-first 방식의 실험 실행, 지표 기록, 차트 생성 및 결과 번들 (bundle) 내보내기 기능을 제공합니다.
• Baseline, Ablation, Seed, Metric, Failure summary, Branch ranking 및 Reproducibility ledger를 지원합니다.
• CS/AI 작업은 회귀 (Regression), 분류 (Classification), 클러스터링 (Clustering), 차원 축소 (Dimensionality reduction), 진단 차트 (Diagnostic plots), 모델 평가 (Model evaluation) 및 논문 수준의 결과 요약을 포함할 수 있습니다.
• 생물정보학 (Bioinformatics) 작업은 Bulk 발현 (Bulk expression), 차이 분석 (Differential analysis), 풍부화 분석 (Enrichment analysis), 단일 세포 (Single-cell) 기초 워크플로우 및 일반적인 연구용 차트를 포함할 수 있습니다.
• 실증 연구 방법론 (Empirical research methods) 기술 (Skill)은 DID, IV, RDD, PSM/IPW, DML, Target trial, TMLE 등의 방법론 요구사항을 실험 메타데이터 (Metadata) 및 게이트 (Gate)로 변환할 수 있습니다.

논문, 리뷰 (Review), 실험 논문 및 공식 연구 보고서는 기본적으로 다음과 같은 LaTeX 번들을 생성합니다:

manuscript.tex

references.bib

citation_audit.json

manuscript.pdf

상위 수준 도구인 manuscript_export는 파일 쓰기, 인용 감사 (Citation audit), LaTeX 컴파일 및 아티팩트 (Artifacts) 전시를 통합적으로 수행합니다. 하위 수준에는 여전히 write_file, citation_audit, present_files가 유지되지만, 공식 논문 인도 시에는 파일 생성이 임시 채팅 답변에 머무는 것을 방지하기 위해 상위 수준의 내보내기 기능을 우선적으로 사용합니다.

현재 PDF 경로는 tectonic을 우선적으로 사용합니다. 컴파일러가 누락되었거나 LaTeX 컴파일에 실패할 경우, 시스템은 명확한 도구 오류를 반환하며, 계속해서 수정할 수 있도록 .tex, .bib 및 감사 (Audit) 파일을 보존합니다.

ResearchQualityAudit는 투고 전 흔히 발생하는 품질 리스크를 다룹니다:

• 문헌 커버리지 부족.
• 본문 내 인용 밀도가 너무 낮음.
• 주제에서 벗어나거나 관련 없는 분야의 문헌 혼입.
• 정량적 증거, 벤치마크 (Benchmark), 케이스 스터디 (Case study) 또는 실험 결과 부족.
• 평가 프레임워크의 실행 과제 및 해결책 누락.
• 반복적인 표현, 절대적인 어조, 전환 문구 누락 및 과정 설명 잔류.

기본 전략은 먼저 자동으로 검색을 보완하고, 증거와 벤치마크를 보충하며, 취약한 섹션을 재작성하는 것입니다. 수정 예산이 소진되면 인적 게이트 (Human gate) 단계로 진입하며, 구체적인 구제 보고서를 반환합니다.

• 각 채팅/스레드 (Chat/thread)는 독립적인 workspace, uploads, outputs 및 memory.json을 가집니다.
• 새 대화는 빈 메모리에서 시작하며, 다른 대화의 사용자 프로필이나 연구 상태를 상속하지 않습니다.
• 현재 대화의 보고서, BibTeX, PDF, 차트, 표 및 감사 파일은 스레드 범위의 출력물 (Thread-scoped outputs)에 기록되며, 아티팩트 (Artifact) 패널에서 확인, 미리보기 및 다운로드할 수 있습니다.
• 백엔드에서는 호환성을 위해 기존 Memory API를 유지하지만, 프런트엔드에서는 더 이상 전역 메모리 설정 페이지를 제공하지 않습니다.

프런트엔드 설정의 "기능 (Features)" 페이지에는 현재 백엔드 구성이 집중적으로 표시됩니다:

• Agents: 기본 오케스트레이터 (Orchestrator), 시스템 에이전트 (System agent), 사용자 정의 에이전트 (Custom agent) 및 서브 에이전트 (Subagent).
• Tools: MCP 서버 (MCP server), 트랜스포트 (Transport), 활성화 (Enabled) 상태, 명령 또는 URL 요약, 마스킹된 (Redacted) 환경 변수/헤더 키.
• Skills: 공용 및 사용자 정의 기술 (Skill)의 이름, 설명, 분류, 활성화 상태 및 라이선스 (License).

이 페이지는 읽기 전용 목록이며, 추가, 삭제, 편집, 활성화, 비활성화 또는 연결 테스트 작업을 제공하지 않습니다. 하위 관리 API는 스크립트 기반 관리 및 호환성 시나리오를 위해 여전히 유지됩니다.

|
v
...

요청 라우팅 (Request routing):

/api/langgraph/* -> LangGraph Server: 에이전트 상호작용, 스레드 (Thread), SSE 스트리밍 (SSE streaming), 장기 실행 런 (Long-running run).
/api/* -> Gateway API: 구성 (Configuration), 기능 (Features), 학술 (Academic), 연구 (Research), 실험 (Experiments), 업로드 (Uploads), 아티팩트 (Artifacts), 실행 (Runs).
/ -> Frontend: Next.js Web UI.

런타임 데이터는 주로 backend/.medrix-flow 또는 MEDRIX_FLOW_HOME이 가리키는 디렉토리에 저장됩니다. 각 스레드의 가상 파일 시스템은 /mnt/user-data/{workspace,uploads,outputs}로 매핑됩니다.

Anaxa 1.0은 기본적으로 오픈 소스 개발 버전으로 출시됩니다. 소스 코드를 다운로드한 후 로컬에서 초기화 및 서비스를 실행하고, 프런트엔드를 통해 모델을 구성하여 직접 사용하거나 2차 개발을 할 수 있습니다. 기본적으로 UI 비밀번호는 활성화되지 않습니다. 이 모드는 로컬 머신 또는 신뢰할 수 있는 로컬 네트워크 환경에 적합하며, 공용 인터넷 프로덕션 배포에는 적합하지 않습니다.

먼저 다음 시스템 도구들을 설치해야 합니다:

• Python 3.12+
• Node.js 22+
• pnpm
• uv
• nginx

설치가 잘 되었는지 확실하지 않다면, 먼저 다음을 실행하세요:

make check

누락된 도구는 검사 결과에서 설치 안내와 함께 제공됩니다. tectonic은 선택 사항이며, LaTeX PDF 생성의 안정성에만 영향을 미칩니다.

git clone <repo-url>
cd <repo-folder>
make bootstrap

make bootstrap은 다음 세 가지 작업을 수행합니다:

• 로컬 의존성(dependencies) 사용 가능 여부를 확인합니다.
• 다음 로컬 설정 파일들을 생성합니다:
  config.yaml
  , .env
  , frontend/.env
  , extensions_config.json
• 백엔드(backend) 및 프론트엔드(frontend) 의존성을 설치합니다.

생성된 설정 파일들은 모두 .gitignore에 포함되어 있어 소스 코드와 함께 커밋되지 않습니다. 실제 API Key는 수동으로 파일에 작성할 필요가 없으며, 이후 프론트엔드에서 설정하면 됩니다.

make dev

실행 후 다음 주소로 접속하세요:

http://localhost:6200

페이지에 처음 접속하면, 왼쪽 하단의 "설정 및 더 보기(Settings and more) -> 구성(Configuration)"을 열고, 최소 하나 이상의 채팅 모델과 API Key를 추가하세요. 저장 후 새로운 대화를 시작할 수 있습니다.

로컬 개발 서비스는 동시에 다음과 같이 실행됩니다:

• Frontend: http://localhost:6201
• Gateway API: http://localhost:6202
• LangGraph Server: http://localhost:6203
• Nginx unified entry: http://localhost:6200

로컬 머신에 Python/Node/nginx를 설치하고 싶지 않다면, Docker 개발 모드를 사용할 수 있습니다:

make docker-init
make docker-start

접속 주소는 동일하게 다음과 같습니다:

http://localhost:6200

Docker 개발 환경 중지:

make docker-stop

명령	설명
make bootstrap	최초 사용 시: 의존성 확인, 로컬 설정 생성, 의존성 설치
make check	Node.js, pnpm, uv, nginx 설치 여부 확인
make install	백엔드(backend) 및 프론트엔드(frontend) 의존성 설치
make dev	개발 모드 실행, 핫 리로드(hot reload) 지원
make dev-daemon	개발 서비스를 백그라운드에서 실행
make stop	로컬 서비스 중지
make docker-start	Docker 개발 모드 실행
make docker-stop	Docker 개발 모드 중지
make verify	백엔드 lint/test, 프론트엔드 lint/typecheck/unit/build 실행
make release-check	배포 전 로컬 secrets, 캐시, 메모리 및 실행 데이터가 Git에 의해 추적되고 있는지 확인

실행 후 http://localhost:6200에 접속하여 "설정 및 더 보기 -> 구성"을 엽니다:

• 모델 제공자(provider), 모델 이름 및 API Key를 추가합니다.
• 네트워크 검색, 웹 크롤링, 학술 검색 증강(RAG) 등의 도구 API Key를 구성합니다.
• 이미지 생성이 필요한 경우, Google AI Studio 또는 OpenAI 호환 이미지 인터페이스를 구성합니다.
• 저장하면 설정이 로컬 파일에 기록되고 핫 리로드(hot reload)됩니다.

프론트엔드의 "기능(Features)" 페이지는 현재 사용 가능한 에이전트(Agents), MCP 도구(tools) 및 스킬(Skills)을 읽기 전용으로 보여주며, 추가, 삭제, 편집, 활성화 또는 비활성화 기능은 제공하지 않습니다.

config.yaml과 extensions_config.json은 여전히 사용 가능하며, 스크립트 기반 관리나 심층적인 커스텀에 적합합니다:

• config.yaml: 모델, 도구 그룹, 샌드박스 제공자(sandbox provider), 체크포인터(checkpointer), 메모리(memory), 리서치 게이트(research gate) 및 품질 전략.
• extensions_config.json: MCP 서버 및 스킬의 활성화 상태.
• make config-upgrade: 새 필드를 기존 config.yaml에 병합.

로컬의 .env, 데이터베이스, 메모리, 컨텍스트, 업로드된 파일, 출력 파일, 캐시 및 로그는 프로젝트와 함께 공개되어서는 안 됩니다. 배포 전에 다음을 실행하세요:

make release-check

검사에 실패하면 출력에 나열된 경로를 먼저 처리한 후 공개 저장소(repository)에 push하세요. 이 명령은 로컬 파일을 삭제하지 않습니다.

오픈 소스 개발 버전은 기본적으로 UI 비밀번호가 설정되어 있지 않습니다. 서비스를 공용 네트워크에 노출하려면 MEDRIX_FLOW_ENV=production, MEDRIX_FLOW_UI_PASSWORD, 그리고 선택 사항인 MEDRIX_GATEWAY_ADMIN_TOKEN을 설정하십시오.

Anaxa 1.0은 사용자 대상 브랜드 마이그레이션(Brand Migration)을 완료했습니다. 기존 스크립트, 데이터 디렉토리, 환경 변수 및 import 경로의 파괴를 방지하기 위해 다음 기술적 식별자들은 그대로 유지됩니다:

• Python import package:
  medrix_flow

• Python distribution / workspace package names 내의 호환되는 명칭

• 환경 변수 (Environment variables):
  MEDRIX_FLOW_*

• 런타임 디렉토리 (Runtime directory):
  .medrix-flow

• 관리자 헤더 (Admin header):
  x-medrix-admin-token

• 일부 Docker container, Compose project 및 cleanup prefix

이 명칭들은 호환 계층(Compatibility layer)에 속하며, 새로운 제품 브랜드를 의미하지는 않습니다.

내장 도구 (Built-in tools):

academic_research: 문헌 검색, 증거 카드 (evidence cards), 참조 (references) 및 감사 (audit).
research_assistant: 연구 생명주기 (research lifecycle), 원장 (ledger), 게이트 (gate), 품질 감사 (quality audit) 및 run_pipeline.
experiment_lab: 실험 실행, 차트, 지표 (metrics) 및 재현성 번들 (reproducibility bundle).
manuscript_export: LaTeX/BibTeX/audit/PDF 원클릭 내보내기.
citation_audit: LaTeX 인용 키 (citation key), 본문 인용 및 주장 (claim) 지원 확인.
present_files: 아티팩트 (artifacts)를 전시하고, .tex 파일을 위한 PDF 미리보기를 생성 시도.
ask_clarification: 사용자의 확인이 필요할 때 구조화된 옵션 생성.
visual_quality_check / visual_refinement_check: 시각적 결과물의 품질 게이트 (quality gate).

• 샌드박스 도구 (sandbox tools): bash, ls, read_file, write_file, str_replace.

기술 (Skills)은 skills/public 및 skills/custom에서 발견되며, extensions_config.json에 따라 주입됩니다. 현재 공개된 기술은 학술 글쓰기, 문헌 정리, 실증 연구 방법, 연구용 도표, 데이터 분석, 기술 도식, PPT, PDF, 플러그인/기술 생성 등의 시나리오를 지원합니다.

• 운영 환경 (Production environment)에서는 MEDRIX_FLOW_ENV=production을 설정해야 합니다.
• Nginx를 통해 UI/API를 노출할 때는 MEDRIX_FLOW_UI_PASSWORD를 설정해야 합니다. 그렇지 않으면 보호된 페이지와 API는 fail-closed 방식으로 접근이 거부됩니다.
• 스크립트 기반 관리를 위해 MEDRIX_GATEWAY_ADMIN_TOKEN을 설정할 수 있으며, x-medrix-admin-token 요청 헤더를 통해 보호된 인터페이스에 접근할 수 있습니다.
• 로컬 샌드박스는 신뢰할 수 있는 개발 환경에 적합합니다. 운영 환경이나 신뢰할 수 없는 코드를 실행할 때는 AioSandboxProvider 또는 provisioner/Kubernetes 모드로 전환해야 합니다.
• Bash 도구 호출은 보안 감사 및 경로 격리를 거치며, 스레드(thread) 가상 경로는 /mnt/user-data로 제한됩니다.
• 외부 코드 실행, 장기 실험, 실험 코드의 자동 수정 및 최종 논문 릴리스(release)는 기본적으로 인간 게이트 (human gate)를 거쳐야 합니다.

.
├── backend/
│ ├── app/gateway/ # FastAPI Gateway API
...

백엔드 (Backend):

cd backend
make lint
make test

프론트엔드 (Frontend):

cd frontend
pnpm lint
pnpm typecheck
...

전체 로컬 검증 (Full local verification):

make verify

본 프로젝트는 MIT License를 사용합니다. Anaxa의 엔지니어링 기초는 LangGraph, Next.js, FastAPI, 오픈 소스 에이전트 (agent) 도구 생태계 및 여러 연구 자동화 프로젝트의 아이디어를 흡수했지만, 프로젝트의 목표는 항상 "연구 부조종사 (Research Co-pilot)"입니다. 즉, 모델이 연구자의 판단, 증거 책임 및 최종 저자 책임을 대체하는 것이 아니라 연구 작업에 참여하도록 하는 것입니다.