typedef-ai/fenic

fenic – 인간과 에이전트를 위한 의미적 DataFrame

무엇인가요

대규모 언어 모델(LLM)로 구동되는 의미적 연산자(예: extract, classify, summarize, embed, 그리고 의미적 조인 등)를 익숙한 DataFrame/SQL 스타일 API(pandas, PySpark, Spark SQL 등)에 확장하는 Python 라이브러리입니다.
extract, classify, summarize, embed, 의미적 조인 등의 연산자는 쿼리 계획의 일급 요소로 다뤄지며, LLM 호출은 자동으로 관리됩니다(배치 처리, 레이트 제한, 캐시, 비용 계산).

왜 중요한가요

비구조화된 텍스트(티켓, 로그, 녹취록, PDF 등)는 일반적으로 일회성 정규식이나 프롬프트로 처리되며, 재현이 어렵습니다.
fenic은 이러한 탐색 과정을 형식화되고 검사 가능한 파이프라인으로 전환하여 버전 관리, 재실행, 인간과 AI 에이전트 모두가 호출할 수 있도록 합니다.
파이프라인 자체가 아티팩트가 됩니다: explain()로 논리 계획을 확인하고, 행의 계보를 추적하며, 토큰/비용 메트릭을 확인할 수 있으며, Model Context Protocol(MCP)를 통해 결과를 도구로 공개할 수 있습니다.

핵심 개념

개념	설명
세션	설정(앱 이름, 모델 제공자, 레이트 제한)을 보유합니다. 모든 DataFrame은 세션에서 생성됩니다.
의미적 연산자 (`fc.semantic.*`)	쿼리 내에서 LLM을 호출하는 함수: `extract(col, PydanticSchema)`, `classify(col, classes)`, `predicate(prompt, …)`, `reduce(prompt, column)`, `embed(col)` 등.
지연 파이프라인	연산은 논리 계획으로 기록되며 필요할 때만 실행되어, LLM 응답의 자동 배치 및 캐시가 가능합니다.
형식화된 출력	결과는 Pydantic 모델로 검증되어 보장된 타입을 가진 컬럼을 제공합니다.
MCP 통합	테이블/뷰를 형식화된 도구로 게시할 수 있어 에이전트가 호출할 수 있으며, DataFrame 결과를 재사용 가능한 AI 도구로 전환할 수 있습니다.

일반적인 워크플로우 (60초 데모)

import fenic as fc
from pydantic import BaseModel, Field

class Ticket(BaseModel):
    product: str = Field(description="제품 이름")
    sentiment: str = Field(description="positive, neutral, or negative")
    issue: str = Field(description="문제의 1줄 요약")

session = fc.Session.get_or_create(
    fc.SessionConfig(
        app_name="quickstart",
        semantic=fc.SemanticConfig(
            language_models={"mini": fc.OpenAILanguageModel(model_name="gpt-4o-mini", rpm=500)}
        ),
    )
)

df = session.create_dataframe([
    {"id": 1, "text": "보고서의 CSV 내보내기 기능이 계속 타임아웃됩니다."},
    {"id": 2, "text": "새로운 대시보드는 좋아요, 하지만 모바일에서 SSO 로그인이 작동하지 않습니다."},
])

tickets = (
    df.select("id", fc.semantic.extract("text", Ticket).alias("t"))
      .unnest("t")
)

tickets.show()

LLM은 Ticket에 정의된 필드를 추출하고, 일반 DataFrame을 반환하여 쿼리, 조인, 내보내기 가능합니다.

주요 기능

의미적 조인 – 자연어로 관계를 설명하여 두 테이블을 조인합니다.
임베딩 기반 조인 (sim_join) 및 클러스터링 (with_cluster_labels).
다양한 소스 유형 내장 지원 – CSV, Parquet, Markdown, 녹취록, PDF, JSON, S3, Hugging Face 데이터셋.
관측성 – explain(), lineage(), 쿼리별 토큰/비용 메트릭, 응답 캐시.
확장 가능한 제공자 레이어 – OpenAI, Anthropic, Google, Cohere, OpenRouter; 여러 모델을 등록하고 연산자별로 선택 가능.
CLI 헬퍼 – fenic check (파이프라인의 정적 린트), fenic skill install (Claude Code, Cursor 등 코딩 에이전트용 스킬 정의 설치).

예시 사용 사례

평가 트레이스 분석 – 실패 유형 분류, 근본 원인 요약 집계, MCP 도구로 결과 공개.
고객 지원 – 티켓 텍스트를 대시보드 및 하류 자동화용 구조화된 행으로 변환.
연구 에이전트 – 뉴스 기사, 팟캐스트, 회의 녹취록을 읽어 엔티티 추출, 요약, 검색 가능한 테이블로 저장.
로그 트리지 – 자유형 로그에서 의미적 추출, 유사 사건 클러스터링, 사건 보고서 생성.

설치

pip install fenic               # 핵심
pip install "fenic[pdf,cluster,sim-join]"  # PDF 파싱, 클러스터링 등 옵션 기능

적절한 제공자 API 키 설정 (예: OPENAI_API_KEY).

커뮤니티 및 기여

지원용 디스코드 커뮤니티.
다양한 분야를 다루는 노트북이 포함된 예제 리포지토리 fenic-examples.
오픈 기여 가이드라인; PR 환영합니다.

결론 fenic은 진정한 오픈소스 프로젝트로, LLM 기반 의미적 처리를 DataFrame 추상화에 통합하여 비구조화된 데이터 파이프라인을 재현 가능하고, 검사 가능하며, 인간과 AI 에이전트 간에 공유 가능한 것으로 만듭니다.

typedef-ai/fenic

fenic – 인간과 에이전트를 위한 의미적 DataFrame

관련