taxia-core 1.0.1

Korean Tax AI Library with Graph-RAG

TAXIA

Korean Tax AI Library with Graph-RAG

RAG (Retrieval-Augmented Generation) + Graph-RAG library for Korean tax consultation and question-answering.

All answers are provided with clear legal citations and complete audit trail support.

Current Status: v1.0.0 Official Release ✅

All development phases completed (Phase 0-7)

• ✅ Qdrant vector search integration
• ✅ Claude/OpenAI LLM support
• ✅ Neo4j Graph-RAG support
• ✅ CLI tools (taxia index, taxia ask, taxia health)
• ✅ FastAPI REST API server (7 endpoints)
• ✅ Korean tax law data loader
• ✅ 40+ tests (100% pass rate)
• ✅ Comprehensive documentation (7 markdown + official documentation site)
• ✅ Public GitHub repository
• ✅ PyPI deployment complete
• ✅ GitHub Pages documentation site deployment
• ✅ Complete audit trail support

Status: Production ready | PyPI installable 🚀

---

Key Features

Core Capabilities

• Citation Enforcement: All answers require minimum 2+ legal citations
• Audit Trail: Complete query-response record tracking via trace_id
• Query Optimization: Intent detection, keyword extraction, feedback integration
• Korea-Optimized: Query processing and answers optimized for Korean tax law and culture
• Vector Search: Semantic search using Qdrant + sentence-transformers
• LLM Integration: Intelligent answer generation via Claude/OpenAI API
• Graph-RAG: Tax law relationship graph search via Neo4j (optional)
• CLI Tools: taxia index, taxia ask, taxia health, taxia config
• REST API: FastAPI-based HTTP server (7 endpoints)
• Provided Data: Korean tax law JSON parsing and indexing support

---

📦 Installation & First Use

1️⃣ Install from PyPI (Recommended)

pip install taxia-core

2️⃣ Data Setup (Important!)

TAXIA uses local tax law data. Users must prepare their own data.

Quick Option 1: Automatic Download from Hugging Face 🚀 (NEW!)

# Download all data from Hugging Face Hub
taxia download

# Or download specific year
taxia download --year 2024

Data downloads to: ~/.taxia/data/

Then index it:

taxia index ~/.taxia/data

Data Source: xaikorea0/taxia-korean-tax-laws on Hugging Face Hub

Quick Option 2: Automatic Setup (Recommended for Manual Data) 🎯

python -m taxia setup-data

Or:

python scripts/setup_data.py

This script automatically handles:

• ✅ Environment configuration file creation
• ✅ Data directory structure setup
• ✅ Required folder creation
• ✅ Data validation

Python API Usage

from taxia import DataDownloader

# Download all data
downloader = DataDownloader(username="xaikorea0")
data_path = downloader.download_all()

# Or download specific year
downloader.download_year(2024)

# Verify downloaded data
print(downloader.verify_data())

Manual Setup

See DATA_SETUP.md for details

# 1. Environment setup
cp .env.example .env
# Set TAX_DATA_PATH in .env

# 2. Create data folder
mkdir -p data/koreantaxlaw/{2024,2023,2022}

# 3. Place tax law files
cp your_tax_data/2024/*.json data/koreantaxlaw/2024/
cp your_tax_data/2023/*.json data/koreantaxlaw/2023/

3️⃣ Basic Usage

from taxia import TaxiaEngine

engine = TaxiaEngine()
response = engine.query("What is the corporate tax rate?")

print(response.answer)      # AI answer
print(response.citations)   # Legal citations

---

📚 Documentation

Official Documentation Site

👉 https://xaikorea.github.io/taxia

User Guides 👥

• 📖 Quick Start - Get started in 5 minutes ⭐ Start here!
• 🔧 Data Setup Guide
• 💡 Python Usage Examples (16 examples)
• 🌐 REST API Usage
• 💻 CLI Tool Usage

Developer Documentation 🔧

• ⚡ TaxiaEngine API
• 🌐 REST API Endpoints
• 📝 CLI Commands
• 🏗️ System Architecture
• 🔐 Data Security Guide

Project Information 📋

• 🛣️ Roadmap
• 📖 Changelog
• 🤝 Contributing Guide

Development Installation

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

---

📊 Data Structure

Local Data Folder Organization

TAXIA reads Korean tax law data from local folders.

data/koreantaxlaw/          (Set via TAX_DATA_PATH environment variable)
├── 2024/
│   ├── corporate_tax_law.json
│   ├── corporate_tax_law_regulation.json
│   ├── corporate_tax_law_enforcement_decree.json
│   ├── vat_law.json
│   ├── vat_law_regulation.json
│   ├── vat_law_enforcement_decree.json
│   ├── income_tax_law.json
│   ├── income_tax_law_regulation.json
│   └── income_tax_law_enforcement_decree.json
├── 2023/
│   └── ... (same files)
└── 2022/
    └── ... (same files)

Data File Format

JSON format (Recommended):

[
  {
    "title": "Corporate Tax Law",
    "category": "Article 1",
    "content": "This law establishes the criteria and procedures for levying corporate income tax.",
    "article": "Article 1"
  },
  ...
]

CSV format:

title,category,content,article
Corporate Tax Law,Article 1,This law establishes the criteria and procedures for...,Article 1
...

Data Validation

Check configured data:

python -c "from taxia.retrieval.data_loader_user import DataSetupHelper; DataSetupHelper.print_setup_info()"

Validate in Python code:

from taxia.retrieval.data_loader_user import DataLoader

loader = DataLoader()
print("Available years:", loader.get_available_years())
print("2024 tax laws:", loader.get_available_laws(2024))
print("Data statistics:", loader.get_statistics())

---

🚀 Usage Methods

Using as Python Library

Basic Usage

from taxia import TaxiaEngine

# Create engine (automatically loads configuration)
engine = TaxiaEngine()

# Query tax law
response = engine.query("What is the VAT reporting deadline?")

print("Answer:", response.answer)
print("Citations:")
for citation in response.citations:
    print(f"  - {citation.source}: {citation.content}")

Advanced Usage (LLM Customization)

from taxia import TaxiaEngine
from taxia.config import Config

# Customize environment configuration
config = Config.initialize()
config.llm.model = "gpt-4"
config.llm.temperature = 0.3

engine = TaxiaEngine(config=config)
response = engine.query("...")

Load and Validate Data

from taxia.retrieval.data_loader_user import DataLoader

loader = DataLoader()

# Check available data
years = loader.get_available_years()
laws = loader.get_available_laws(2024)

# Load tax law data
law_data = loader.load_law(2024, "Corporate Tax Law")

# Batch load across years
all_data = loader.load_all_years("Corporate Tax Law")

# Validate data
validation_result = loader.validate_data()
print(validation_result)

Using CLI Tools

# Check environment configuration
taxia config

# Query tax law
taxia ask "What is the VAT rate?"

# Index data (Qdrant)
taxia index

# Check system health
taxia health

# Run data setup wizard
taxia setup-data

Using REST API

# Start server
taxia serve --port 8000

# Call API (in another terminal)
curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"query": "What is the corporate tax rate?"}'

# Example response:
# {
#   "query": "What is the corporate tax rate?",
#   "answer": "The basic corporate tax rate is 10-25%.",
#   "citations": [
#     {
#       "source": "Corporate Tax Law Article 55",
#       "content": "..."
#     }
#   ]
# }

See REST API Documentation for more details

---

🛠️ Configuration Options

Environment Variables

Set in .env file:

# Data path
TAX_DATA_PATH=./data/koreantaxlaw

# LLM configuration
LLM_PROVIDER=claude  # or openai
LLM_MODEL=claude-3-sonnet-20240229
LLM_API_KEY=your-api-key

# Vector DB (Qdrant)
QDRANT_HOST=localhost
QDRANT_PORT=6333

# Graph DB (Neo4j) - Optional
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password

See .env.example file for full details

---

🔐 Data Security

TAXIA stores tax law data locally only. Data is never transmitted externally.

• Data excluded from Git: Protected by .gitignore
• Environment-based configuration: Sensitive info like API keys managed via environment variables
• Local vector DB: Embeddings stored locally in Qdrant
• Audit trail: All queries logged (optional)

See SECURITY_DATA_MANAGEMENT.md for detailed security information

---

📋 Examples

Example 1: Basic Query

from taxia import TaxiaEngine

engine = TaxiaEngine()

# Query
response = engine.query("How to calculate earned income?")
print(f"Answer: {response.answer}")

Example 2: Year-over-Year Comparison

from taxia.retrieval.data_loader_user import DataLoader

loader = DataLoader()

# 2023 data
laws_2023 = loader.load_all_years("Corporate Tax Law")
# Compare with 2024 data...

Example 3: Audit Trail

from taxia import TaxiaEngine

engine = TaxiaEngine()
response = engine.query("...")

print(f"Trace ID: {response.trace_id}")
print(f"Timestamp: {response.timestamp}")

See examples/ folder for more examples

---

🤝 Contributing

TAXIA is an open-source project. We welcome contributions!

• Read Contributing Guide
• Submit issues or create pull requests
• Report bugs and request features

---

📞 Support

Troubleshooting

1. Configuration issues: See "Troubleshooting" section in DATA_SETUP.md
2. API issues: See REST API Documentation
3. Data issues: See Data Security Guide

Contact

• 📧 Issues: https://github.com/xaikorea/taxia/issues
• 📖 Documentation: https://xaikorea.github.io/taxia
• 💬 Discussions: https://github.com/xaikorea/taxia/discussions

---

📄 License

This project is licensed under Apache License 2.0.

---

🙏 Acknowledgments

• Qdrant - Vector search
• LangChain - LLM integration
• sentence-transformers - Embeddings
• Claude/OpenAI - LLM APIs

---

Last Updated: December 2024
Version: 1.0.0