Architecture deep-dive

이 페이지의 쓰임

코드베이스에 처음 들어오는 사람을 위한 지도입니다. 모든 서브시스템을 경로와 함께 평면으로 나열한 시스템 색인이 카탈로그라면, 이 페이지는 경로입니다. 무엇부터 읽을지, 요청 하나가 코드를 실제로 어떻게 지나는지 보여 줍니다.

서브시스템 지도

프로덕션 코드는 두 패키지입니다. core/는 범용 자율 에이전트 런타임이고, plugins/는 1차 보조 플러그인(petri_audit, seed_generation)입니다. core/의 서브시스템은 5계층 스택에 정렬됩니다.

Self-Improving  core/self_improving/  train.py + measure/fitness/gate/ledger + loop/{mutate,observe,inject}
Agent           core/agent/           AgenticLoop(while tool_use), sub_agent, system_prompt
Harness         core/cli/             thin CLI + commands/ + IPC 클라이언트
                core/server/          serve 데몬. ipc_server(CLIPoller) + supervised(메신저 폴러)
                core/messaging/       바인딩 기반 게이트웨이 라우팅
                core/hooks/           라이프사이클 이벤트 (HookSystem)
                core/orchestration/   LaneQueue, TaskGraph, compaction, tool offload
                core/scheduler/       cron/이벤트 트리거 + 예약 작업
                core/wiring/          부트스트랩 주입 (container, bootstrap, scheduling)
                core/ui/              터미널 렌더 (event_renderer, latex)
Runtime         core/tools/           도구 레지스트리 + deferred loading + PolicyChain
                core/mcp/             MCP 클라이언트 (manager, stdio_client)
                core/memory/          5-tier 컨텍스트 + 세션 저장소
                core/skills/          스킬 레지스트리
                core/llm/prompts/     프롬프트 템플릿 + 해시 핀
                core/audit/           감사 결과 추출 (dim_extractor)
                core/observability/   SQLite events, transcripts, session metrics, OTLP
                core/config/          Settings + 레이어 해석 (explain)
                core/auth/            OAuth, 프로필, 쿨다운
Model           core/llm/             라우터 + 어댑터 레지스트리
                core/llm/providers/   Anthropic / OpenAI / Codex / GLM

최상위에는 진입 모듈이 몇 개 있습니다. core/runtime.py의 GeodeRuntime이 부트스트랩이고, core/paths.py가 모든 디렉터리 경로를 한곳에서 해석하며, core/mcp_server.py가 geode-mcp 진입점입니다. 계층 경계가 왜 이렇게 그어졌는지는 왜 5계층인가에 있습니다.

흐름 추적 하나. 대화형 요청

geode  (thin REPL, core/cli/)
   │  자유 텍스트 → IPCClient.send_prompt  (~/.geode/cli.sock)
   ▼
CLIPoller  (core/server/ipc_server/poller.py)  ── session + global 레인 획득
   ▼
AgenticLoop  (core/agent/loop/agent_loop.py)
   ▼  매 라운드
시스템 프롬프트 + 컨텍스트 조립  (core/agent/system_prompt.py + core/memory/)
   ▼
LLM 호출  (core/llm/router/ → core/llm/providers/)
   ▼
도구 요청?  ── 예 → core/tools/ 실행 → 결과 관찰 → 다음 라운드
   │
   └ 아니오 → 답변 스트리밍 (core/ui/event_renderer.py)

thin CLI는 직접 일하지 않습니다. IPC로 geode serve 데몬에 붙고, 데몬 안의 단일 GeodeRuntime이 작업을 실행합니다. 라운드마다 메모리 계층과 프롬프트 레이어가 컨텍스트로 합쳐지고, 라우터가 어댑터를 고르고, 모델이 도구를 요청하면 레지스트리가 실행합니다. 턴이 끝나는 경로들은 안쪽 agentic 루프에 있습니다.

흐름 추적 둘. 자기개선 사이클

auto-trigger 또는 운영자  (core/wiring/scheduling.py → loop/auto_trigger.py)
   ▼
변이 제안 + 적용  (core/self_improving/loop/mutate/runner.py, 7 behaviour kinds)
   ▼
Petri 감사 서브프로세스  (measure.py → geode audit → plugins/petri_audit/)
   │  GEODE_WRAPPER_OVERRIDE로 변이된 스캐폴드를 주입한 같은 AgenticLoop를 측정
   ▼
fitness 계산  (fitness.py, 22-dim 판정 → 스칼라)
   ▼
margin 게이트  (gate.py)
   ├ 통과 → 승격. baseline.json 갱신 + baseline_archive.jsonl append  (ledger.py)
   └ 실패 → 되돌림. SoT를 변이 전으로 복원

두 루프는 코드를 공유하되 기록으로 만납니다. 감사는 안쪽 루프와 같은 AgenticLoop를 측정 대상으로 돌리고, 게이트를 통과한 변이만 승격되어 git 추적 원장에 계보로 남습니다. 가중치 갱신은 어디에도 없습니다. 전체 흐름은 아우터 루프, 측정 프레임워크는 Petri × GEODE에 있습니다.

더 깊이

시스템 색인. 모든 서브시스템과 경로의 평면 카탈로그.
왜 5계층인가. 경계가 그 자리에 있는 이유.
왜 self-hosting 하네스인가. 런타임과 빌드 라인이 기본 단위를 공유하는 이유.
왜 ratchet 규율인가. drift를 막는 형태.

아키텍처 심화

이 페이지의 쓰임

서브시스템 지도

추천 읽기 순서

흐름 추적 하나. 대화형 요청

흐름 추적 둘. 자기개선 사이클

더 깊이