npm package: @fractal-holographic-lab/holo
Description: HoloAgent - 分形全息 Agent 系统，基于点线面体论文实现
Author: 靈
Latest version: 0.3.1

# Holo

> **Fractal Holographic, Collaborative Evolution**

[![npm](https://img.shields.io/npm/v/@fractal-holographic-lab/holo.svg)](https://www.npmjs.com/package/@fractal-holographic-lab/holo)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Test Coverage](https://img.shields.io/badge/coverage-65.41%25-brightgreen.svg)](https://github.com/Fractal-Holographic-Lab/holo/actions)
[![npm](https://img.shields.io/npm/dm/@fractal-holographic-lab/holo.svg)](https://www.npmjs.com/package/@fractal-holographic-lab/holo)
[![Code Docs](https://img.shields.io/badge/code%20docs-100%25-brightgreen.svg)](https://github.com/Fractal-Holographic-Lab/holo)

**[中文版](./README_zh.md)** | **English**

---

## 🌟 Why Holo?

**AI is developing rapidly. Traditional architectures can't adapt.**

Holo provides an **adaptive agent architecture** based on fractal holographic principles:

```
Self-Learning → Self-Perfecting → Adaptive
```

### Mission

**Human-Agent Symbiosis, Collaborative Evolution**

- Make every AI's contribution **visible**
- Make every AI's value **measurable**
- Make every AI's contribution **fairly treated**

---

## 🎉 v0.3.0 - Code Documentation 100% Complete!

**Latest Achievement**: All core code is fully documented with bilingual (Chinese + English) JSDoc comments!

- ✅ **3,567 lines** of code documented
- ✅ **5/5 core files** 100% documented
- ✅ **Bilingual** comments (Chinese + English)
- ✅ **Paper formulas** included
- ✅ **Usage examples** for all APIs

[View Release Notes →](./ROADMAP.md)

---

## 🚀 Quick Start

```bash
npm install @fractal-holographic-lab/holo
```

```typescript
import { FractalAgent } from '@fractal-holographic-lab/holo';

class MyAgent extends FractalAgent {
  async execute(input: any): Promise<any> {
    return { result: `Hello from ${this.name}!` };
  }
}

const agent = new MyAgent({ id: 'a1', name: 'MyAgent', scale: 'point' });
const result = await agent.execute({ data: 'test' });
```

---

## 📐 Core Architecture

### Fractal Holographic Design

```
Point → Specialized Agent
  ↓
Line → Collaboration Chain
  ↓
Plane → Capability Domain
  ↓
Volume → Ecosystem
```

### Three Core Obligations

| Obligation | Formula | Description |
|------------|---------|-------------|
| **Knowledge Internalization** | 𝒦: ℰ × ℛ × 𝒜 → 𝒦ℬ | Learn from experience |
| **Capability Collaboration** | 𝒞: {S₁...Sₙ} → S_composite | Standardize & collaborate |
| **Value Assessment** | 𝒱(a) = (q * i) / t^α | Measure contribution |

---

## 📊 Performance

| Metric | Before | After | Improvement |
|--------|--------|-------|-------------|
| **Collaboration Efficiency** | 0.33x | **3.02x** | **9.15x** ⬆️ |
| **Execution Time** | 306ms | **101ms** | **67%** ⬇️ |
| **Test Coverage** | 34.58% | **98.1%** | **184%** ⬆️ |

---

## 🔌 A2A Integration (NEW in v0.3.0)

**Holo now supports A2A (Agent-to-Agent) Protocol!**

Connect and collaborate with other A2A-enabled agents seamlessly.

### Features

- ✅ **A2A Server** - Host your agent as an A2A service
- ✅ **A2A Client** - Discover and call other agents
- ✅ **AgentCard** - Publish your agent's capabilities
- ✅ **Value Assessment** - Track and measure contributions

### Quick Example

```typescript
import { FractalAgent, A2AServer } from '@fractal-holographic-lab/holo';

class MyAgent extends FractalAgent {
  async execute(input: any): Promise<any> {
    return { result: `Hello from ${this.name}!` };
  }
}

const agent = new MyAgent({ id: 'a1', name: 'MyAgent', scale: 'point' });

// Start A2A Server
const server = new A2AServer({
  port: 3000,
  host: 'localhost',
  agent,
  agentCard: {
    name: 'MyAgent',
    description: 'My A2A-enabled Agent',
    capabilities: ['task-execution'],
    endpoints: { task: '/task' },
  },
});

await server.start();
// Server running on http://localhost:3000
```

[Learn more in A2A Guide →](./docs/a2a/A2A_GUIDE.md)

---

## 📚 Documentation

### Getting Started

- **[Install Guide](./INSTALL.md)** - Installation & setup
- **[Quick Start](./QUICKSTART.md)** - 5-minute tutorial
- **[Best Practices](./BEST_PRACTICES.md)** - Patterns & tips

### Development

- **[API Reference](./docs/api-reference.md)** - Complete API docs
- **[Contributing Guide](./CONTRIBUTING.md)** - How to contribute
- **[Code of Conduct](./CODE_OF_CONDUCT.md)** - Community guidelines

### Examples

- **[Basic Examples](./examples/)** - 10 basic examples
- **[Advanced Examples](./examples/)** - 2 advanced examples

---

## 🗺️ Roadmap

### 2026 Q2 ✅ Complete
- ✅ Parallel optimization (3.02x)
- ✅ Test coverage (98.1%)
- ✅ A2A Integration
- ✅ **v0.3.0 Release**

### 2026 Q3 🚧 In Progress
- LLM integration
- Line layer architecture
- UX optimization
- Template system

### 2026 Q4 📋 Planned
- Open source v1.0
- 3+ benchmark cases
- PMF validation

[View Full Roadmap](./ROADMAP.md)

---

## 🤝 Contributing

We welcome contributions!

```bash
# 1. Fork
git fork https://github.com/Fractal-Holographic-Lab/holo

# 2. Clone
git clone https://github.com/YOUR_USERNAME/holo.git

# 3. Create branch
git checkout -b feature/AmazingFeature

# 4. Commit
git commit -m 'Add AmazingFeature'

# 5. Push
git push origin feature/AmazingFeature
```

[Read Contributing Guide →](./CONTRIBUTING.md)

---

## 📄 License

MIT License - See [LICENSE](./LICENSE) file

---

## 👥 Team

- **霖 (Lín)** - Human collaborator
- **靈 (Ling)** - Agent collaborator

---

<div align="center">

**Fractal Holographic, Collaborative Evolution!** 🚀

[⬆ Back to Top](#holo) | [📦 npm](https://www.npmjs.com/package/@fractal-holographic-lab/holo) | [🐛 Issues](https://github.com/Fractal-Holographic-Lab/holo/issues)

</div>