taxia-core 1.0.1
Korean Tax AI Library with Graph-RAG
License: Apache-2.0
Requires Python: >=3.9
Keywords: tax, rag, graph-rag, korea, ai, llm

# 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.

[![PyPI](https://img.shields.io/pypi/v/taxia-core.svg)](https://pypi.org/project/taxia-core/)
[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
[![Tests](https://img.shields.io/badge/tests-40%20passed-brightgreen)]()
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](./LICENSE)
[![GitHub](https://img.shields.io/badge/github-xaikorea%2Ftaxia-black)](https://github.com/xaikorea/taxia)

## 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)
```bash
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!)
```bash
# 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:
```bash
taxia index ~/.taxia/data
```

**Data Source**: [xaikorea0/taxia-korean-tax-laws](https://huggingface.co/datasets/xaikorea0/taxia-korean-tax-laws) on Hugging Face Hub

#### Quick Option 2: Automatic Setup (Recommended for Manual Data) 🎯
```bash
python -m taxia setup-data
```

Or:
```bash
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
```python
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](DATA_SETUP.md)** for details

```bash
# 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
```python
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](https://xaikorea.github.io/taxia)**

#### User Guides 👥
- **[📖 Quick Start - Get started in 5 minutes](DATA_SETUP.md)** ⭐ Start here!
- [🔧 Data Setup Guide](docs/data_setup.md)
- [💡 Python Usage Examples (16 examples)](docs/examples.md)
- [🌐 REST API Usage](docs/api_usage.md)
- [💻 CLI Tool Usage](examples/cli_usage.md)

#### Developer Documentation 🔧
- [⚡ TaxiaEngine API](docs/api/engine.md)
- [🌐 REST API Endpoints](docs/api/rest.md)
- [📝 CLI Commands](docs/api/cli.md)
- [🏗️ System Architecture](docs/ARCHITECTURE.md)
- [🔐 Data Security Guide](SECURITY_DATA_MANAGEMENT.md)

#### Project Information 📋
- [🛣️ Roadmap](ROADMAP.md)
- [📖 Changelog](CHANGELOG.md)
- [🤝 Contributing Guide](CONTRIBUTING.md)

### Development Installation
```bash
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):**
```json
[
  {
    "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:
```bash
python -c "from taxia.retrieval.data_loader_user import DataSetupHelper; DataSetupHelper.print_setup_info()"
```

Validate in Python code:
```python
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
```python
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)
```python
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
```python
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

```bash
# 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

```bash
# 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](docs/api_usage.md) for more details

---

## 🛠️ Configuration Options

### Environment Variables

Set in `.env` file:

```env
# 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](SECURITY_DATA_MANAGEMENT.md) for detailed security information

---

## 📋 Examples

### Example 1: Basic Query
```python
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
```python
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
```python
from taxia import TaxiaEngine

engine = TaxiaEngine()
response = engine.query("...")

print(f"Trace ID: {response.trace_id}")
print(f"Timestamp: {response.timestamp}")
```

See [examples/](examples/) folder for more examples

---

## 🤝 Contributing

TAXIA is an open-source project. We welcome contributions!

- Read [Contributing Guide](CONTRIBUTING.md)
- Submit issues or create pull requests
- Report bugs and request features

---

## 📞 Support

### Troubleshooting

1. **Configuration issues**: See "Troubleshooting" section in [DATA_SETUP.md](DATA_SETUP.md)
2. **API issues**: See [REST API Documentation](docs/api_usage.md)
3. **Data issues**: See [Data Security Guide](SECURITY_DATA_MANAGEMENT.md)

### 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](LICENSE).

---

## 🙏 Acknowledgments

- [Qdrant](https://qdrant.tech/) - Vector search
- [LangChain](https://python.langchain.com/) - LLM integration
- [sentence-transformers](https://www.sbert.net/) - Embeddings
- Claude/OpenAI - LLM APIs

---

**Last Updated**: December 2024  
**Version**: 1.0.0