소개

Contexta는 딥러닝 훈련 및 운영 환경에서의 Observability를 목적으로 로컬 환경에서 사용 가능한 워크플로를 위한 라이브러리입니다.

이 라이브러리는 Python SDK, CLI, 로컬 워크스페이스, 표준 데이터 모델을 하나의 일관된 흐름으로 제공하며 다음과 같은 기능을 제공합니다.

또한, ML 실행에서 발생하는 관측 정보를 캡처하고, 저장하고, 쿼리하고, 비교하고, 리포트로 정리하고, 필요할 때 복구할 수 있게 합니다.

이 라이브러리의 목적은 작업이 끝난 뒤에도 로컬에 남아 있는 구조화된 기록을 통해 그 실행에서 어떤 일이 일어났는지 다시 확인할 수 있게 하는 것입니다.

설치

pip install contexta

또는 uv를 사용할 수 있습니다.

uv add contexta

Contexta의 기본 런타임은 duckdb만을 필요로 합니다. 프레임워크 연동은 필요한 경우에 한하여 선택적으로 설치할 수 있습니다.

첫 수집을 진행하기

시작하기에서는 머신러닝, 딥러닝, 그리고 LLM 워크플로에서 바로 실행해 볼 수 있는 예제를 제공합니다.

각 예제에서는 로컬 .contexta/ 워크스페이스를 만들고, 예제 코드를 실행한 결과를 기반으로 나중에 검토할 수 있는 기록을 수집합니다.

Contexta는 다음과 같은 방식으로 사용할 수 있습니다.

• Python에서는 import contexta로 시작합니다.
• CLI에서는 contexta <subcommand> 구조로 실행합니다.
• 관측 기록은 프로젝트의 .contexta/ 워크스페이스 아래에 저장됩니다.

Contexta가 추적하는 것

Contexta는 실험에서 발생하는 다음의 관측성 데이터를 표준화된 기록으로 정리합니다.

• 프로젝트 (Project), 실행 (Run), 단계 (Stage), 작업 (Run), 배치 (Batch), 샘플 (Sample), 배포 (Deployment)
• 구조화된 이벤트 (Event), 메트릭 (Metric), 스팬 (Span), 불완전한 상태 (Degraded State)
• 아티팩트 (Artifact), 매니페스트 (Manifest), 해시 (Hash), 가져오기 (Import), 내보내기 (Export), 보존된 기록 (Record)
• 리니지 (Lineage), 출처 (Provenance), 환경 (Environment)
• 쿼리 (Query), 비교 (Comparison), 진단 (Diagnostics), 추세 (Trend), 리포트 (Report)

이 모델은 로컬 워크스페이스를 중심으로 설계되었습니다.

즉, 별도의 원격 서비스나 외부 SaaS에 의존하지 않아도 관측 데이터를 생성하고, 조사하고, 비교하고, 복구할 수 있습니다.

워크스페이스가 프로젝트 옆에 생성되기 때문에 노트북, CI 작업, 오프라인 리뷰, 자율 에이전트의 워크트리와도 자연스럽게 함께 사용할 수 있습니다.

핵심 구성

Contexta는 여러 Observability 도구를 따로 조합하는 방식이 아니라, 하나의 제품 안에서 캡처부터 복구까지 이어지는 흐름을 제공합니다.

구성 요소	역할
통합 퍼사드	Python SDK와 CLI를 통해 Contexta 기능에 접근하는 단일 진입점
로컬 워크스페이스	.contexta/ 아래에 관측 기록과 아티팩트를 저장하는 로컬 저장소
표준 계약	검증과 직렬화를 거치는 정형 데이터 모델
조사 계층	쿼리, 비교, 진단, 리니지 추적, 리포트 생성을 담당하는 계층
복구 계층	백업, 복구, 재생, 전송 작업을 담당하는 계층

다음에 읽을 문서

• 시작하기는 빠른 예제를 더 자세한 온보딩 흐름으로 확장합니다.
• 핵심 개념은 Contexta의 데이터 모델과 주요 개념을 설명합니다.
• 도구 및 인터페이스는 Python SDK, CLI, 로컬 워크스페이스의 사용 경계를 설명합니다.
• API 레퍼런스는 Python 인터페이스를 문서화합니다.
• 운영 가이드는 백업, 복구, 재생, 전송 워크플로를 다룹니다.
• 케이스 스터디는 캡처된 기록이 실제 운영 상황에서 어떻게 쓰이는지 보여줍니다.

제품 인터페이스

인터페이스	역할
Contexta	사용자 워크플로에서 시작점이 되는 기본 퍼사드
contexta.config	설정 모델, 프로필, 환경 변수 오버라이드
contexta.contract	표준 모델, 검증, 직렬화, 참조
contexta.capture	런타임 캡처 스코프와 이벤트 발행
contexta.store.*	메타데이터, 레코드, 아티팩트를 저장하는 계층
contexta.interpretation	쿼리, 비교, 진단, 리니지, 추세, 알림, 리포트 서비스
contexta.recovery	백업, 복구, 재생, 전송 작업

세부 모듈 경계를 직접 다뤄야 하는 경우가 아니라면 Contexta에서 시작하세요.