Metadata-Version: 2.4
Name: yi-jing-agent
Version: 0.1.0
Summary: ䷀ I Ching Six Lines AI Agent Framework — Fusing ancient I Ching wisdom with modern AI agent architecture
Author: yayasasapig
License-Expression: MIT
Project-URL: Homepage, https://github.com/yayasasapig/yi-jing-agent
Project-URL: Repository, https://github.com/yayasasapig/yi-jing-agent
Project-URL: Issues, https://github.com/yayasasapig/yi-jing-agent/issues
Keywords: i-ching,yi-jing,ai-agent,lifecycle,fault-tolerance,六爻,易經,agent-framework,reflection,resilience
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pycodestyle; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Dynamic: license-file
Dynamic: requires-python

# ䷀ Yi-Jing Agent — I Ching Six Lines AI Agent Lifecycle Framework

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![CI](https://github.com/yayasasapig/yi-jing-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/yayasasapig/yi-jing-agent/actions/workflows/ci.yml)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
[![PyPI](https://img.shields.io/badge/PyPI-pip%20install%20yi--jing--agent-blue)](https://github.com/yayasasapig/yi-jing-agent)

> **Fusing ancient I Ching wisdom with modern AI agent architecture.**
> A structured lifecycle framework that prevents goal drift, enables graceful degradation, and brings philosophical depth to AI agent execution.

---

## 🧠 What is Yi-Jing Agent?

Modern AI agents suffer from three structural problems:
1. **Goal Drift** — Agents forget the original intent mid-task
2. **Blind Impulse** — Agents rush to call APIs without proper planning
3. **Crash with No Recovery** — One error cascades into total failure

The **I Ching (易經) Six Lines framework** solves this by imposing a **6-stage lifecycle** on every task, where each stage (爻) has strict behavioral rules and output gates:

```
Line           Agent Behavior              Output Gate
────────────────────────────────────────────────────────────────
初爻 (Hidden Dragon) → Pure understanding, NO actions → Task Graph
二爻 (Dragon in Field) → Sandbox & prototyping   → Feasibility Report
三爻 (Alert Dragon) → 3D Reflection Engine      → Safety Report
四爻 (Leaping Dragon) → Authorization Gate       → Confirm / Pivot
五爻 (Flying Dragon) → Full execution            → Core Payload
上爻 (Regretful Dragon) → Memory compression     → LTM Write
```

## 🔄 Dynamic Fault Tolerance with Hexagram Mutation

When any line encounters an error, the system triggers **dynamic hexagram mutation (動爻變卦)** — XOR flipping that line's bit and looking up the new hexagram's strategy:

```
Initial (111111 ䷀ Qian) ──[API Timeout at Line 5]──→ flip bit5
                                                    ↓
Mutation (111011 ䷉ Lu) ──→ Strategy: degrade to Line 2 sandbox
```

## 🧿 3D Reflection Engine (錯綜互卦)

At Line 3, the agent performs a mandatory three-dimensional reflection:

| Dimension | I Ching Concept | Question |
|:----------|:---------------|:---------|
| 🔍 **Interlocking (互卦)** | Hidden motive | What does the user *really* need? |
| ⚔️ **Opposite (錯卦)** | Adversarial view | Where would this plan fail *if everything is wrong*? |
| 👁️ **Reversed (綜卦)** | User perspective | How will the end-user experience this output? |

---

## 🚀 Quick Start

### Prerequisites
- Python 3.10+
- An AI agent platform (Hermes Agent, OpenClaw, AutoGPT, etc.)

### Install
```bash
git clone https://github.com/yayasasapig/yi-jing-agent.git
cd yi-jing-agent
# Copy the skill to your agent's skill directory
cp -r skill/* ~/.hermes/skills/
# Or use the Python library directly
pip install -e .
```

### Basic Usage (Python)
```python
from src.agent_state import YiJingAgentState
from src.executor import YiJingAgentExecutor
import asyncio

async def main():
    executor = YiJingAgentExecutor()
    result = await executor.execute("Analyze this website's pricing strategy")
    print(f"Status: {result['status']}")
    print(f"Hexagram path: {' → '.join(
        t.transition_name for t in result['hexagram_history']
    )}")

asyncio.run(main())
```

### For Hermes/OpenClaw Agents
Load the skill in your `SOUL.md` or task prompt:

```
Load the `yi-jing-agent` skill to activate the 六爻 lifecycle.
```

---

## 📂 Repository Structure

```
yi-jing-agent/
├── README.md                 # ← You are here
├── LICENSE                   # MIT
├── CONTRIBUTING.md           # How to contribute
├── docs/
│   ├── 六爻AI-Agent架構設計書.md  # Original Chinese design document (37KB)
│   └── architecture-overview.md  # English architecture summary
├── skill/
│   └── SKILL.md              # Hermes/OpenClaw skill definition
├── src/
│   ├── agent_state.py        # Core YiJingAgentState
│   ├── executor.py           # Full lifecycle executor
│   ├── hexagram_table.py     # 64 hexagrams → strategies
│   ├── reflection.py         # 3D reflection engine
│   └── yao_positions.py      # Line definitions & enums
├── examples/
│   └── six-yao-lifecycle-demo.md  # Walkthrough demo
└── .github/
    └── workflows/
        └── ci.yml            # GitHub Actions CI
```

---

## 📖 Documentation

| Resource | Language | Description |
|:---------|:---------|:------------|
| [Design Document](docs/六爻AI-Agent架構設計書.md) | 🇭🇰 Chinese (Cantonese) | Full 37KB architectural blueprint |
| [Architecture Overview](docs/architecture-overview.md) | 🇬🇧 English | English summary of the framework |
| [Skill Definition](skill/SKILL.md) | 🇭🇰 Chinese | Ready-to-use agent skill |
| [Lifecycle Demo](examples/six-yao-lifecycle-demo.md) | 🇭🇰 Chinese | Real-world walkthrough with摘日 |

---

## 🌍 Community & Contributions

This project is **open for everyone** to use, remix, and improve!

- **Share your hexagram strategies** — Found a new failure mode? Add it to the table!
- **Translate** — Help translate the docs to Japanese, Korean, English
- **Build tools** — Dashboard, VSCode extension, visualization
- **Report issues** — Found a bug in the lifecycle? Open an issue!

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

## 📜 License

MIT — Free for personal and commercial use.

---

## 🙏 Credits

- **Concept**: yayafu × Gemini conversation distillation
- **Implementation**: Orchestrator Nova (Hermes Agent)
- **Platform**: OpenClaw Agent Team

---

> **「An agent that knows its time uses wisdom to move mountains.」**
> **「識得時機嘅 Agent，用智慧四兩撥千斤。」**
