Oxy Custom 프로젝트 개요 분석

Oxy는 Rust로 작성된 오픈 소스 agentic analytics 프레임워크입니다. 이 프로젝트는 AI 기반 데이터 분석에 소프트웨어 개발 생명주기 원칙을 적용하여, 에이전트 생성부터 프롬프트 테스팅, 프로덕션 배포까지의 구조화된 워크플로우를 제공합니다.

1. 프로젝트 구조 개요

1.1 핵심 디렉토리 구성

oxy-cust/
├── crates/                    # Rust 크레이트 구조
│   ├── core/                 # 핵심 애플리케이션 로직
│   ├── entity/               # 데이터 엔터티 정의
│   ├── migration/            # 데이터베이스 마이그레이션
│   └── py/                   # Python 바인딩
├── web-app/                  # 웹 애플리케이션 프론트엔드
├── docs/                     # 프로젝트 문서
├── examples/                 # 사용 예제
├── json-schemas/             # JSON 스키마 정의
├── oss/                      # 오픈 소스 관련 파일
├── sample_project/           # 샘플 프로젝트
├── docker-compose.yml        # Docker 구성
├── Dockerfile               # 컨테이너 이미지 빌드
└── Cargo.toml               # Rust 워크스페이스 설정

1.2 프로젝트 특징

## The framework for agentic analytics

Oxy is an open-source framework for agentic analytics. It is declarative by design and written in Rust. 
Oxy is built with the following product principles in mind: 
- open-source
- performant
- code-native
- declarative
- composable
- secure

핵심 설계 원칙:

오픈 소스: Apache-2.0 라이센스 하에 완전 공개
고성능: Rust의 메모리 안전성과 성능 활용
코드 네이티브: 선언적 설정을 통한 코드 중심 접근
조합 가능: 모듈식 아키텍처로 유연한 확장
보안: Rust의 안전성 보장과 보안 설계

2. Cargo 워크스페이스 구조 분석

2.1 워크스페이스 설정

[workspace]
members = ["crates/core", "crates/entity", "crates/migration", "crates/py"]
default-members = ["crates/core"]
resolver = "2"

[workspace.dependencies]
tokio = { version = "1.45", features = ["full"] }
sea-orm = { version = "1.1.11", features = [
  "sqlx-sqlite",
  "sqlx-postgres", 
  "runtime-tokio-rustls",
  "macros",
] }
sea-orm-migration = { version = "1.1.11", features = [
  "sqlx-sqlite",
  "sqlx-postgres",
  "runtime-tokio-rustls",
] }
log = { version = "0.4" }

워크스페이스 특징:

모듈화: 기능별로 분리된 크레이트 구조
의존성 공유: 워크스페이스 레벨에서 공통 의존성 관리
비동기 처리: Tokio 기반 완전 비동기 런타임
데이터베이스: Sea-ORM을 통한 SQLite/PostgreSQL 지원

2.2 핵심 의존성 분석

# 핵심 애플리케이션 의존성
anyhow = "1.0.98"                    # 에러 처리
axum = { version = "0.8.4", features = ["macros"] }  # 웹 프레임워크
clap = { version = "4.5.38", features = ["derive"] } # CLI 파싱
async-openai = {version = "0.28.1", features = ["byot"]} # OpenAI API
duckdb = { version = "=1.1.1", features = ["bundled"] }  # 임베디드 분석 DB

의존성 카테고리:

비동기 및 웹 서비스

Tokio: 비동기 런타임 및 I/O
Axum: 현대적 웹 프레임워크
Tower: 미들웨어 및 서비스 추상화

데이터 처리

DuckDB: 고성능 분석 데이터베이스 엔진
Arrow: 컬럼형 메모리 포맷
ConnectorX: 다양한 데이터베이스 연결

AI 및 ML

async-openai: OpenAI API 클라이언트
LanceDB: 벡터 데이터베이스
PyO3: Python 상호 운용성

CLI 및 사용자 인터페이스

Clap: 명령행 인터페이스 파싱
Colored: 컬러 터미널 출력
Tabled: 테이블 형식 출력

3. 핵심 모듈 아키텍처

3.1 Core 크레이트 구조

// src/lib.rs
mod adapters;      // 데이터 소스 어댑터
mod agent;         // 에이전트 시스템
pub mod api;       // REST API 서버
pub mod cli;       // CLI 인터페이스
pub mod config;    // 설정 관리
pub mod db;        // 데이터베이스 클라이언트
pub mod errors;    // 에러 타입 정의
mod eval;          // 평가 시스템
pub mod execute;   // SQL 실행 엔진
pub mod mcp;       // Model Context Protocol
pub mod semantic;  // 시맨틱 검색
pub mod service;   // 비즈니스 서비스
pub mod theme;     // UI 테마
mod tools;         // 유틸리티 도구
pub mod utils;     // 공통 유틸리티
pub mod workflow;  // 워크플로우 엔진

3.2 애플리케이션 진입점

// src/main.rs
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Rustls 암호화 프로바이더 설정
    rustls::crypto::aws_lc_rs::default_provider()
        .install_default()
        .expect("Failed to install rustls crypto provider");
        
    // 패닉 핸들러 설정
    setup_panic!(Metadata::new(env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"))
        .authors("Robert Yi <robert@oxy.tech>")
        .homepage("github.com/oxy-hq/oxy")
        .support("- For support, please email robert@oxy.tech")
    );
    
    dotenv().ok();
    
    // 로깅 시스템 초기화
    let args: Vec<String> = env::args().collect();
    let log_to_stdout = args.iter().any(|a| a == "serve");
    init_tracing_logging(log_to_stdout);
    
    // CLI 실행
    match cli().await {
        Ok(_) => {}
        Err(e) => {
            tracing::error!(error = %e, "Application error");
            eprintln!("{}", format!("{}", e).error());
            exit(1)
        }
    };
    Ok(())
}

진입점 특징:

비동기 메인: Tokio 런타임에서 전체 애플리케이션 실행
암호화 설정: AWS LC RS 프로바이더로 TLS 보안
패닉 처리: 사용자 친화적 에러 메시지
구조화된 로깅: Tracing 기반 로그 시스템

4. 개발 환경 및 도구 체인

4.1 Rust 설정

[workspace.package]
edition = "2024"
rust-version = "1.86.0"
publish = false
description = "Oxy"
authors = ["oxy engineers"]
documentation = "https://docs.oxy.tech"
exclude = ["examples/", "tests/"]

Rust 버전 정책:

Rust 2024 에디션: 최신 언어 기능 활용
최소 버전: 1.86.0으로 최신 안정성 확보
비공개: 워크스페이스 레벨에서 crates.io 발행 비활성화

4.2 개발 도구 구성

// package.json
{
  "scripts": {
    "lint": "eslint . --fix",
    "format": "prettier --write .",
    "type-check": "tsc --noEmit"
  },
  "devDependencies": {
    "@commitlint/cli": "^18.0.0",
    "@commitlint/config-conventional": "^18.0.0",
    "eslint": "^8.50.0",
    "prettier": "^3.0.3"
  }
}

4.3 품질 관리 도구

# .github/workflows 구조
.husky/               # Git 훅 관리
.lintstagedrc.js     # 스테이지된 파일 린트
commitlint.config.js # 커밋 메시지 규칙
eslint.config.js     # JavaScript 린트 설정
.prettierrc.js       # 코드 포맷팅 규칙
rustfmt.toml         # Rust 포맷팅 설정
typos.toml          # 오타 검사 설정

품질 보증:

Husky: Git 커밋/푸시 훅으로 자동 검사
Commitlint: 컨벤셔널 커밋 규칙 강제
ESLint/Prettier: JavaScript/TypeScript 코드 품질
Rustfmt: Rust 코드 스타일 통일
Typos: 문서 및 코드 오타 검사

5. 컨테이너 및 배포 전략

5.1 Docker 멀티 스테이지 빌드

# Dockerfile (추정 구조)
FROM rust:1.86-alpine AS builder
WORKDIR /app
COPY . .
RUN cargo build --release --workspace

FROM alpine:latest
RUN apk add --no-cache ca-certificates
COPY --from=builder /app/target/release/oxy /usr/local/bin/
EXPOSE 8080
CMD ["oxy", "serve"]

5.2 Docker Compose 서비스

# docker-compose.yml
version: '3.8'
services:
  oxy:
    build: .
    ports:
      - "8080:8080"
    environment:
      - DATABASE_URL=sqlite:///data/oxy.db
    volumes:
      - ./data:/data

6. 설치 및 배포 자동화

6.1 크로스 플랫폼 설치

# 메인 설치 스크립트 (Linux/macOS/WSL)
bash <(curl --proto '=https' --tlsv1.2 -LsSf https://get.oxy.tech)

# Homebrew (macOS)
brew install oxy-hq/oxy/oxy

# 특정 버전 설치
OXY_VERSION="0.1.0" bash <(curl --proto '=https' --tlsv1.2 -sSf \
    https://raw.githubusercontent.com/oxy-hq/oxy/refs/heads/main/install_oxy.sh)

6.2 릴리즈 관리

// release-please-config.json
{
  "packages": {
    ".": {
      "release-type": "rust",
      "package-name": "oxy"
    }
  }
}

릴리즈 자동화:

Release Please: 자동 버전 관리 및 체인지로그
Self Update: 애플리케이션 내장 업데이트 기능
크로스 플랫폼: Linux, macOS, Windows 지원

7. 보안 및 컴플라이언스

7.1 보안 스캔

# .deepsource.toml
version = 1
analyzers = [
  { name = "rust", enabled = true },
  { name = "docker", enabled = true },
  { name = "secrets", enabled = true }
]

7.2 라이센스 관리

# .whitesource
{
  "scanSettings": {
    "baseBranches": ["main"]
  },
  "checkRunSettings": {
    "vulnerableCheckRunConclusionLevel": "failure"
  }
}

8. 모니터링 및 관찰성

8.1 구조화된 로깅

// 트레이싱 로깅 초기화
fn init_tracing_logging(log_to_stdout: bool) {
    let env_filter = EnvFilter::try_from_default_env()
        .unwrap_or_else(|_| EnvFilter::new("info"))
        .add_directive("oxy=debug".parse().unwrap())
        .add_directive("tower_http=debug".parse().unwrap());
        
    let log_file_path = std::path::Path::new(&client::get_state_dir()).join("oxy.log");
    // 파일 또는 stdout으로 로그 출력
}

로깅 전략:

Tracing: 구조화된 로깅 및 분산 추적
환경별 설정: 개발/프로덕션 환경에 따른 로그 레벨
JSON 출력: 프로덕션에서 기계 가독 형식
파일 로테이션: 로그 파일 자동 관리

9. 결론

Oxy는 현대적인 Rust 개발 패턴을 충실히 따르는 고품질 agentic analytics 프레임워크입니다:

9.1 주요 강점

현대적 아키텍처: 비동기 처리와 모듈화 설계
타입 안전성: Rust의 컴파일 타임 보장
성능 최적화: Zero-cost abstractions와 메모리 안전성
개발자 경험: 풍부한 CLI와 자동화된 도구 체인

9.2 기술적 혁신

Agentic Analytics: AI 에이전트와 데이터 분석의 융합
선언적 설계: 코드 네이티브 접근으로 구성의 단순화
다중 언어 지원: Rust 코어에 Python 바인딩 제공
임베디드 분석: DuckDB 통합으로 고성능 분석 엔진

다음 포스트에서는 애플리케이션의 진입점과 초기화 과정을 상세히 분석해보겠습니다.

David Lee

Oxy Custom 프로젝트 개요 분석 - Rust 기반 Agentic Analytics 프레임워크