도구 및 인터페이스
이 문서는 Contexta 라이브러리의 주요 인터페이스와 권장 사용 경로를 설명합니다.
기본 원칙은 간단합니다.
- 처음에는
Contexta에서 시작하세요. - 더 세밀한 제어가 필요할 때만 하위 네임스페이스를 직접 사용하면 됩니다.
시작점
처음 사용하는 경우에는 다음 import를 권장합니다.
from contexta import Contexta
Contexta는 Contexta 라이브러리를 사용할 때 가장 먼저 만나는 기본 객체입니다. 복잡한 하위 모듈을 직접 다루지 않아도, 설정을 준비하고 작업 공간을 연결한 뒤 결과를 확인하고 비교할 수 있습니다.
인터페이스 카테고리
Contexta 문서에서는 인터페이스를 다음 세 가지 등급으로 구분합니다.
Stable- 권장되는 공개 API입니다. 일반 사용자와 외부 코드가 의존해도 되는 인터페이스입니다.
Advanced- 공개 API이지만 주로 운영자, 고급 사용자, 복구 워크플로를 위한 인터페이스입니다.
Internal- 구현 세부 사항입니다. 직접 import하거나 외부 코드에서 의존해서는 안 됩니다.
공용 인터페이스 맵
| 사용할 기능 | 등급 | 무엇을 할 때 쓰나요? | 임포트 적합도 |
|---|---|---|---|
Contexta | Stable | 실행 기록, 조회, 비교, 진단, 리포트 생성 | 예. 여기서 시작하세요. |
contexta.config | Stable | 워크스페이스 위치, 프로젝트명, 환경별 설정 지정 | △ (설정 변경 시) |
contexta.contract | Stable | Contexta에서의 데이터 형식과 검증 규칙 관리 | ✕ |
contexta.capture | Stable | 실행 중 Observability 데이터 수집 | △ (기록 시) |
contexta.store.metadata | Stable | 메타데이터 관련 데이터 읽기/쓰기 | ✕ |
contexta.store.records | Stable | 레코드 관련 데이터 읽기/쓰기 | ✕ |
contexta.store.artifacts | Stable | 아티팩트 관련 데이터 읽기/쓰기 | ✕ |
contexta.interpretation | Stable | 실험 간 비교 · 진단 · 리포트 생성 | △ (분석 시) |
contexta.recovery | Advanced | 워크스페이스에 대한 백업 · 복원 · 재생 | ✕ |
| CLI | Stable용 | 터미널에서 실행 기록 확인 및 운영 작업을 수행 | |
| 내장 HTTP/UI | Stable | 저장된 결과 조회 |
인터페이스 세부 사항
Contexta
대부분의 사용자는 Contexta에서 시작하면 됩니다.
다음과 같은 경우에 사용합니다.
- 주요 Python 진입점이 필요할 때
- 설정과 워크스페이스 바인딩을 하나의 객체에서 관리하고 싶을 때
- 쿼리, 비교, 진단, 리니지, 리포트 기능을 한 곳에서 접근하고 싶을 때
Contexta는 일반 사용자에게 권장되는 기본 인터페이스입니다.
contexta.config
설정을 명시적으로 제어해야 할 때 사용합니다.
예를 들어 다음 작업에 적합합니다.
UnifiedConfig를 직접 구성- 프로필 선택
- 환경 변수 기반 설정 재정의
- 설정 모델 직접 사용
기본 Contexta 생성 방식만으로는 충분하지 않을 때 사용하세요.
contexta.contract
표준 데이터 모델을 직접 다뤄야 할 때 사용합니다.
주요 용도는 다음과 같습니다.
- 정규화 모델
StableRef- 검증
- 직렬화
contexta.capture
캡처 흐름을 더 직접적으로 제어해야 할 때 사용합니다.
다음 기능을 다룹니다.
- 런타임 스코프
- 캡처 방출
- 캡처 결과 타입
- 싱크 관련 동작
퍼사드 수준의 캡처 기능만으로 부족할 때 사용하세요.
contexta.store.metadata
메타데이터 저장소에 직접 접근해야 할 때 사용합니다.
다음 리소스를 다룹니다.
- 프로젝트
- 실행
- 스테이지
- 관계
- 프로버넌스
- 메타데이터 마이그레이션 및 무결성 헬퍼
contexta.store.records
레코드 저장소를 직접 다뤄야 할 때 사용합니다.
주요 용도는 다음과 같습니다.
- 레코드 추가
- 스캔
- 재생
- 내보내기
- 레코드 계층의 무결성 검사 및 복구
contexta.store.artifacts
아티팩트 저장소를 직접 다뤄야 할 때 사용합니다.
다음 작업에 적합합니다.
- 아티팩트 수집
- 아티팩트 검증
- 아티팩트 가져오기 및 내보내기
- 보존 계획
- 격리 및 복구 흐름
contexta.interpretation
저장된 표준 데이터를 읽고 분석할 때 사용합니다.
다음 기능을 제공합니다.
- 쿼리
- 비교
- 진단
- 리니지
- 리포트
contexta.recovery
복구 및 운영자 워크플로를 위한 인터페이스입니다.
다음 기능을 제공합니다.
- 재생
- 백업
- 복구
contexta.adapters
contexta.adapters는 외부 시스템과의 선택적 통합을 제공합니다.
외부 의존성이 필요 없는 기본 어댑터는 다음과 같습니다.
| 어댑터 | 용도 |
|---|---|
contexta.adapters.export | CSV 내보내기 헬퍼 |
contexta.adapters.html | HTML 렌더링 헬퍼 |
contexta.adapters.notebook | 노트북 표시 인터페이스 |
일부 어댑터는 선택 의존성이 필요합니다.
| 어댑터 | 용도 | 필요 extra |
|---|---|---|
contexta.adapters.otel | OpenTelemetry 브릿지 | [otel] |
contexta.adapters.mlflow | MLflow Tracking 브릿지 | [mlflow] |
필요한 의존성이 설치되어 있지 않으면 DependencyError가 발생합니다.
StdoutSink는 별도 extra 없이 contexta.capture.sinks에서 사용할 수 있습니다.
자세한 내용은 어댑터를 참고하세요.
ctx.notebook
Jupyter 또는 IPython 환경에서는 ctx.notebook을 사용할 수 있습니다.
ctx.notebook은 다음 기능을 제공합니다.
show_run()compare_runs()show_metric_trend()- DataFrame 변환 헬퍼
IPython이 없는 환경에서도 사용할 수 있으며, 표시 기능은 가능한 범위 안에서 제한적으로 동작합니다.
자세한 내용은 노트북 인터페이스를 참고하세요.
CLI 및 HTTP/UI
CLI
표준 CLI 명령은 contexta입니다.
CLI는 다음 작업에 적합합니다.
- 쉘 중심 워크플로
- 실행 결과 조사
- 비교
- 리포트 생성
- 운영자 작업
내장 HTTP/UI
내장 HTTP/UI는 Observability 데이터들을 읽고 관련된 분석을 수행하기 위한 인터페이스입니다.
다음 경우에 사용합니다.
- 로컬 브라우저 기반 조사
- 읽기 흐름을 위한 JSON 전송
- 동일한 제품 시맨틱을 사용하는 로컬 인터페이스가 필요할 때
어떤 인터페이스를 선택해야 하나요?
바로 시작하려면 Contexta와 README Quickstart를 사용하세요.
설정을 직접 제어해야 한다면 Contexta와 contexta.config를 사용하세요.
표준 모델을 직접 다뤄야 한다면 contexta.contract를 사용하세요.
조사와 리포팅 기능이 필요하다면 Contexta와 contexta.interpretation을 사용하세요.
복구 기능이 필요하다면 contexta.recovery를 사용하세요.
쉘 환경을 선호한다면 CLI를 사용하세요.
다음 읽을거리
다음 문서로 이어집니다: