taxia-core 1.0.0

Korean Tax AI Library with Graph-RAG

TAXIA

Korean Tax AI Library with Graph-RAG

한국 세무 질의응답을 위한 RAG(Retrieval-Augmented Generation) + Graph-RAG 라이브러리입니다.

모든 답변은 명확한 법적 근거와 함께 제공되며, 완전한 감사 추적(Audit Trail)을 지원합니다.

현재 상태: v1.0 정식 릴리스 ✅

모든 개발 단계 완료 (Phase 0-7)

• ✅ Qdrant 벡터 검색 통합
• ✅ Claude/OpenAI LLM 연동
• ✅ Neo4j Graph-RAG 지원
• ✅ CLI 도구 (taxia index, taxia ask, taxia health, taxia config)
• ✅ FastAPI REST API 서버 (7개 엔드포인트)
• ✅ 실제 한국 세법 데이터 로더
• ✅ 40개 단위/통합 테스트 통과 (100%)
• ✅ 포괄적인 문서화 (7개 마크다운 + 공식 문서 사이트)
• ✅ GitHub 저장소 공개
• ✅ PyPI 배포 완료
• ✅ GitHub Pages 문서 사이트 배포
• ✅ 완전한 감사 추적 (Audit Trail)

상태: 프로덕션 레디 🚀 | PyPI 설치 가능 📦

---

주요 특징

핵심 기능 (Phase 1-5 구현 완료)

• 근거 강제(Citations Required): 모든 답변은 최소 2개 이상의 법적 근거를 필수로 포함
• 감사 추적(Audit Trail): trace_id를 통한 완전한 질의-응답 이력 추적
• 질의 정규화: 동의어 처리, 키워드 추출, 의도 감지
• 한국어 최적화: 한국 세법에 특화된 질의 처리 및 응답
• 벡터 검색: Qdrant + sentence-transformers 기반 시맨틱 검색
• LLM 통합: Claude/OpenAI API를 통한 동적 답변 생성
• Graph-RAG: Neo4j 기반 법령 간 관계 그래프 탐색 (선택사항)
• CLI 도구: taxia index, taxia ask, taxia health, taxia config
• REST API: FastAPI 기반 HTTP 서버 (7개 엔드포인트)
• 실제 데이터: 한국 세법 JSON 파싱 및 인덱싱 지원

---

⚡ 빠른 설치 및 사용

PyPI에서 설치 (권장)

pip install taxia-core

기본 사용

from taxia import TaxiaEngine

engine = TaxiaEngine()
result = engine.answer("법인세 신고기한은?")

print(result.answer)      # AI 답변
print(result.citations)   # 법적 근거

더 자세한 정보는 공식 문서를 참조하세요.

---

📚 문서

공식 문서 사이트

🌐 https://contact536.github.io/taxia

• 빠른 시작 - 5분 안에 시작하기
• 설정 가이드 - LLM, 벡터검색 설정
• API 레퍼런스 - 완전한 API 문서
• 예제 코드 - 16가지 실제 예제
• 아키텍처 - 시스템 구조

개발 버전 설치

git clone https://github.com/contact536/taxia.git
cd taxia
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -e ".[dev]"

---

실제 데이터 인덱싱

TAXIA는 koreantaxlaw 폴더의 실제 한국 세법 데이터를 사용할 수 있습니다.

1. 데이터 준비

프로젝트 루트에 koreantaxlaw 폴더를 생성하고 세법 JSON 파일을 추가하세요:

taxia-core/
├── koreantaxlaw/
│   └── 2025/
│       ├── 소득세법.json
│       ├── 소득세법_시행령.json
│       ├── 소득세법_시행규칙.json
│       ├── 부가가치세법.json
│       ├── 법인세법.json
│       └── ...
└── ...

2. Qdrant 시작 (벡터 검색용)

# Docker로 Qdrant 실행
docker run -p 6333:6333 qdrant/qdrant

# 또는 Docker Compose
docker-compose up -d qdrant

3. 실제 데이터 인덱싱

# 2025년 세법 데이터 인덱싱
python examples/index_real_data.py

출력 예시:

======================================================================
TAXIA - 실제 한국 세법 데이터 인덱싱
======================================================================

[1/6] 사용 가능한 데이터 확인 중...
✓ 사용 가능한 연도: 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025
✓ 인덱싱 대상 연도: 2025

[5/6] 2025년 세법 데이터 로드 및 인덱싱 중...
======================================================================
✓ 법인세법.json: 146개 조문 로드
✓ 부가가치세법.json: 70개 조문 로드
✓ 소득세법.json: 207개 조문 로드
... (총 1,107개 조문)
======================================================================

✓ 1107개 조문 인덱싱 완료

---

빠른 시작

기본 사용 (더미 모드)

from taxia import TaxiaEngine

# 엔진 초기화 (더미 모드 - Qdrant 없이 동작)
engine = TaxiaEngine()

# 질의 실행
result = engine.answer("종합소득세 신고기한은 언제인가요?")

# 결과 확인
print(result.answer)
# 출력: 종합소득세 신고기한은 매년 5월 1일부터 5월 31일까지입니다.

print(f"근거 개수: {len(result.citations)}")
# 출력: 근거 개수: 4

print(f"추적 ID: {result.trace_id}")
# 출력: 추적 ID: e2b4914641a4488885a4b21fe966bd1b

전체 답변 출력

print(result.format_full())

종합소득세 신고기한은 매년 5월 1일부터 5월 31일까지입니다.

** 근거 **
1. 소득세법 제70조: 거주자는 해당 과세기간의 다음 연도 5월 1일부터 5월 31일까지...
2. 소득세법 시행령 제134조: 종합소득 과세표준 확정신고는...
3. 부가가치세법 제48조: 사업자는 예정신고기간 또는 과세기간에 대한...
4. 법인세법 제60조: 내국법인은 각 사업연도의 소득에 대한...

※ 본 답변은 일반적인 세무 정보 제공을 목적으로 하며,
   개별 사안에 대한 법적 자문이 아닙니다.
   구체적인 세무 문제는 세무사와 상담하시기 바랍니다.

실제 벡터 검색 사용

from taxia import TaxiaEngine
from taxia.retrieval.korean_tax_law_loader import KoreanTaxLawLoader

# 1. 엔진 초기화 (Qdrant 연결)
engine = TaxiaEngine(
    qdrant_url="http://localhost:6333",
    llm_api_key="your-anthropic-api-key"  # 선택사항
)

# 2. 벡터 검색 활성화
engine.enable_vector_search()

# 3. 실제 세법 데이터 로드 및 인덱싱
documents = KoreanTaxLawLoader.load_directory("./koreantaxlaw", year=2025)
engine._vector_store.index(documents)

print(f"✓ {len(documents)}개 조문 인덱싱 완료")

# 4. 실제 벡터 검색으로 질의
result = engine.answer("소득세법 제70조의 내용은?")

# 이제 실제 세법 조문에서 시맨틱 검색하여 답변 생성
print(result.answer)
print(f"근거: {len(result.citations)}개")

사용자 정보와 함께 질의

result = engine.answer(
    query="프리랜서도 부가세를 내야 하나요?",
    user_id="user_001",
    session_id="session_123"
)

다양한 질의 예제

# 신고기한 질의
result = engine.answer("종합소득세 신고기한은?")

# 부가가치세 질의
result = engine.answer("부가세 신고는 언제 하나요?")

# 법인세 질의
result = engine.answer("법인세 신고 기한을 알려주세요")

# 과세 여부 질의
result = engine.answer("프리랜서도 세금을 내야 하나요?")

---

아키텍처

전체 파이프라인 (Phase 2 구현)

사용자 질의
    ↓
[1] 질의 정규화 (QueryNormalizer) ✅
    - 동의어 처리 (종소세 → 종합소득세)
    - 키워드 추출 (종합소득세, 신고)
    - 의도 감지 (신고기한, 과세여부 등)
    ↓
[2] 문서 검색 (Retriever) ✅
    - 더미 데이터 기반 매칭 (Phase 2)
    - 키워드 기반 필터링
    - 관련성 점수 정렬
    ↓
[3] Graph 확장 (GraphStore) ⏳
    - Phase 4 예정
    ↓
[4] 검증 (Validator) ⏳
    - Phase 3 예정
    ↓
[5] 답변 생성 (LLM) ✅
    - 템플릿 기반 생성 (Phase 2)
    - 의도별 맞춤 답변
    - 자동 Citation 변환
    ↓
[6] 근거 검사 ✅
    - 최소 근거 개수 확인
    - NoCitationError 발생
    ↓
[7] 감사 로그 (Tracer) ✅
    - UUID 기반 trace_id
    - 검색 문서 ID 기록
    - 사용자/세션 정보 저장
    ↓
AnswerResult ✅

---

핵심 컴포넌트

TaxiaEngine

메인 엔진 클래스로, 모든 기능의 진입점입니다.

from taxia import TaxiaEngine
from taxia.config import TaxiaConfig

# 기본 설정
engine = TaxiaEngine()

# 커스텀 설정
config = TaxiaConfig(
    min_citations=3,  # 최소 근거 개수
    top_k=5,          # 검색 결과 개수
    log_traces=True,  # 추적 로그 활성화
)
engine = TaxiaEngine(config=config)

# 질의 실행
result = engine.answer(
    query="종합소득세 신고기한은?",
    user_id="user_001",
    session_id="session_123"
)

데이터 모델 (Pydantic)

모든 데이터 구조는 Pydantic을 사용하여 타입 안정성을 보장합니다.

from taxia.types import Query, Evidence, Citation, AnswerResult, Trace

# Query: 정규화된 질의
query = Query(
    text="종합소득세 신고기한은?",
    normalized_text="종합소득세 신고 기한은?",
    keywords=["종합소득세", "신고"],
    intent="신고기한"
)

# Evidence: 검색된 증거 문서
evidence = Evidence(
    id="law_001",
    title="소득세법 제70조",
    content="거주자는 해당 과세기간의...",
    source="소득세법",
    article="제70조",
    relevance_score=0.95
)

# Citation: 법적 근거 인용
citation = Citation(
    law="소득세법",
    article="제70조",
    content="거주자는 해당 과세기간의..."
)

# AnswerResult: 최종 답변
result = AnswerResult(
    answer="신고기한은 5월 31일까지입니다.",
    citations=[citation],
    trace_id="abc123",
    disclaimer="본 답변은 일반적인 세무 정보..."
)

# Trace: 감사 추적 로그
trace = Trace(
    id="abc123",
    query="종합소득세 신고기한은?",
    retrieved_docs=["law_001", "law_002"],
    citations=[citation],
    user_id="user_001"
)

예외 처리

from taxia.exceptions import (
    NoCitationError,
    LawConflictError,
    OutdatedLawWarning,
    RetrievalError
)

try:
    result = engine.answer("질의")
except NoCitationError as e:
    print(f"근거 부족: {e.message}")
except RetrievalError as e:
    print(f"검색 실패: {e}")
except LawConflictError as e:
    print(f"법령 충돌: {e.conflicting_laws}")

---

테스트

테스트 실행

# 전체 테스트 실행
pytest

# 특정 테스트 파일 실행
pytest tests/test_engine.py

# 상세 출력
pytest -v

# 커버리지 포함 (pytest-cov 필요)
pip install pytest-cov
pytest --cov=taxia --cov-report=term-missing

테스트 결과 (Phase 2)

============================= test session starts =============================
collected 28 items

tests/test_engine.py::TestTaxiaEngine ........................... [ 21%]
tests/test_integration.py::TestPhase2Integration ............ [ 60%]
tests/test_types.py::TestQuery ................................. [100%]

============================== 28 passed in 0.17s ==============================

테스트 커버리지: 핵심 기능 100%

예제 실행

# 기본 사용 예제
python examples/basic_usage.py

# API 서버 (Phase 3에서 완전 구현 예정)
python examples/api_server.py

---

개발 로드맵

Phase	상태	소요	주요 기능
Phase 0	✅ 완료	1일	설계 문서 (SPEC.md, ROADMAP.md)
Phase 1	✅ 완료	1일	프로젝트 스캐폴딩 (33개 파일)
Phase 2	✅ 완료	1일	질의 정규화, 더미 검색, 답변 생성, Trace 로깅
Phase 3	✅ 완료	3-5일	벡터 검색 (Qdrant), LLM 연동 (Claude/OpenAI)
Phase 4	✅ 완료	5-7일	Graph-RAG, Neo4j 연동
Phase 5	✅ 완료	2일	CLI 도구, FastAPI 서버
Phase 6	✅ 완료	1일	GitHub 공개 준비
Phase 7	✅ 완료	2일	Docusaurus 문서 사이트

자세한 내용은 ROADMAP.md를 참조하세요.

---

개발 환경 설정

요구사항

• Python 3.9 이상
• pip 또는 poetry

설치 및 실행

# 저장소 클론
git clone https://github.com/xaikorea/taxia.git
cd taxia-core

# 가상환경 생성 및 활성화
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 개발 의존성 설치
pip install -r requirements-dev.txt

# 테스트 실행
pytest -v

# 코드 포맷팅 (Phase 3+)
black src tests examples
ruff check src tests examples

# 타입 체크 (Phase 3+)
mypy src

---

의존성

필수 (Phase 2)

pydantic>=2.0.0        # 타입 안정성

필수 (Phase 3+)

qdrant-client>=1.7.0           # 벡터 검색
sentence-transformers>=2.2.0   # 임베딩
anthropic>=0.18.0              # Claude API
# 또는
openai>=1.0.0                  # OpenAI API

선택적

fastapi>=0.104.0    # API 서버
uvicorn>=0.24.0     # ASGI 서버
neo4j>=5.14.0       # Graph-RAG
pytest>=7.4.0       # 테스트
black>=23.0.0       # 코드 포맷팅

---

CI/CD

GitHub Actions를 통한 자동화된 테스트 및 배포:

자동 테스트 (test.yml)

• 트리거: Push 및 Pull Request (main, develop 브랜치)
• 플랫폼: Ubuntu, Windows, macOS
• Python 버전: 3.9, 3.10, 3.11, 3.12
• 커버리지: Codecov 자동 업로드

코드 품질 (lint.yml)

• Ruff: 린팅 및 포맷 검사
• mypy: 타입 체크
• Bandit: 보안 스캔

릴리스 자동화 (release.yml)

• 트리거: GitHub Release 생성
• 빌드: 자동 wheel 및 sdist 생성
• 배포: PyPI 자동 배포 (Trusted Publishing)
• 문서: 릴리스 노트 자동 생성

---

프로젝트 구조

taxia-core/
├── SPEC.md                    # 프로젝트 명세서
├── ROADMAP.md                 # 개발 로드맵
├── README.md                  # 이 문서
├── CHANGELOG.md               # 변경 이력
├── CONTRIBUTING.md            # 기여 가이드
├── CODE_OF_CONDUCT.md         # 행동 강령
├── SECURITY.md                # 보안 정책
├── LICENSE                    # Apache 2.0
├── pyproject.toml             # 프로젝트 설정
├── requirements.txt           # 의존성
│
├── .github/                   # GitHub 설정
│   ├── workflows/            # CI/CD
│   │   ├── test.yml         # 테스트 자동화
│   │   ├── lint.yml         # 코드 품질 검사
│   │   └── release.yml      # 릴리스 자동화
│   ├── ISSUE_TEMPLATE/       # 이슈 템플릿
│   │   ├── bug_report.md
│   │   └── feature_request.md
│   └── PULL_REQUEST_TEMPLATE.md
│
├── src/taxia/                 # 소스 코드
│   ├── __init__.py           # 패키지 엔트리포인트
│   ├── engine.py             # TaxiaEngine 메인 클래스 ✅
│   ├── types.py              # Pydantic 모델 (7개) ✅
│   ├── exceptions.py         # 커스텀 예외 (6개) ✅
│   ├── config.py             # 설정 관리 ✅
│   ├── normalizer.py         # 질의 정규화 ✅
│   ├── dummy_data.py         # 더미 법령 데이터 ✅
│   ├── cli/                  # CLI 도구 ✅
│   ├── retrieval/            # 벡터 검색 ✅
│   ├── graph/                # Graph-RAG ✅
│   ├── validation/           # 검증 ✅
│   ├── connectors/           # LLM 커넥터 ✅
│   └── logging/              # 추적 로깅 ✅
│
├── examples/                  # 사용 예제
│   ├── basic_usage.py        # 기본 사용법 ✅
│   ├── api_server.py         # FastAPI 서버 ✅
│   ├── index_real_data.py    # 실제 데이터 인덱싱 ✅
│   └── build_graph.py        # 그래프 구축 ✅
│
└── tests/                     # 테스트 (40개) ✅
    ├── test_engine.py        # 엔진 테스트
    ├── test_types.py         # 타입 테스트
    ├── test_cli.py           # CLI 테스트
    ├── test_api_server.py    # API 서버 테스트
    └── test_integration.py   # 통합 테스트

---

API 서버

FastAPI를 사용한 REST API 서버:

# 서버 실행
python examples/api_server.py

# 또는
uvicorn examples.api_server:app --reload

# 질의 요청
curl -X POST "http://localhost:8000/ask" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "종합소득세 신고기한은?",
    "user_id": "user_001",
    "session_id": "session_123"
  }'

---

라이선스

Apache License 2.0

자세한 내용은 LICENSE 파일을 참조하세요.

---

커뮤니티

기여하기

기여는 언제나 환영합니다! 자세한 내용은 CONTRIBUTING.md를 참조하세요.

행동 강령

우리는 포용적이고 환영하는 커뮤니티를 만들기 위해 노력합니다. CODE_OF_CONDUCT.md를 참조하세요.

보안

보안 취약점을 발견하셨나요? SECURITY.md의 지침에 따라 비공개로 보고해주세요.

기여 방법

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

개발 가이드라인

• 모든 코드는 타입 힌트 사용
• Pydantic 모델로 데이터 검증
• 단위 테스트 작성 필수
• 문서화 (docstring) 권장

---

문의

• GitHub Issues: https://github.com/xaikorea/taxia/issues
• 문서: https://xaikorea.github.io/taxia (Phase 7에서 구축 예정)

---

면책 조항

TAXIA는 일반적인 세무 정보 제공을 목적으로 하며, 개별 사안에 대한 법적 자문이 아닙니다. 구체적인 세무 문제는 반드시 세무사와 상담하시기 바랍니다.

---

Made with ❤️ for Korean Tax Professionals

© 2026 TAXIA Contributors