# Pi Agent Learning Resources

This folder contains comprehensive learning materials for understanding the Pi Agent architecture.

---

## 📚 Documentation Files

| File | Description | Time |
|------|-------------|------|
| **00-README.md** | This file | 5 min |
| **01-ARCHITECTURE-OVERVIEW.md** | Top-down architecture overview with diagrams | 30 min |
| **02-AGENT-LOOP-DETAILED.md** | Core agent loop implementation details | 45 min |
| **03-HOOK-SYSTEM.md** | Complete hook system reference | 45 min |
| **04-SESSION-ARCHITECTURE.md** | Session persistence and tree structure | 45 min |
| **05-TOOL-EXECUTION.md** | Tool execution mechanics | 45 min |
| **06-AGENTHARNESS-REFERENCE.md** | High-level API reference | 45 min |
| **07-DATA-FLOW-STATE.md** | Data flow and state management | 45 min |
| **08-LEARNING-PATH.md** | Step-by-step learning guide | 2 hrs |
| **09-DIAGRAMS.md** | Visual diagrams and flowcharts | 30 min |
| **10-QUICK-START.md** | Quick start guide for Julia reimplementation | 30 min |
| **11-COMPLETE-SUMMARY.md** | Complete reference summary | 20 min |

---

## 🎯 Learning Paths

### Path 1: Fast Track (4-5 hours)

**Goal**: Understand enough to start implementing

1. **01-ARCHITECTURE-OVERVIEW.md** - Big picture
2. **10-QUICK-START.md** - Quick start guide
3. **02-AGENT-LOOP-DETAILED.md** - Core loop (skim)
4. **11-COMPLETE-SUMMARY.md** - Reference

**Then**: Start implementing in Julia

### Path 2: Thorough (10-12 hours)

**Goal**: Deep understanding before implementation

1. **01-ARCHITECTURE-OVERVIEW.md** - 30 min
2. **02-AGENT-LOOP-DETAILED.md** - 45 min
3. **03-HOOK-SYSTEM.md** - 45 min
4. **04-SESSION-ARCHITECTURE.md** - 45 min
5. **05-TOOL-EXECUTION.md** - 45 min
6. **06-AGENTHARNESS-REFERENCE.md** - 45 min
7. **07-DATA-FLOW-STATE.md** - 45 min
8. **09-DIAGRAMS.md** - Reference throughout

**Then**: Follow **08-LEARNING-PATH.md** for implementation

### Path 3: Comprehensive (15-20 hours)

**Goal**: Master the entire system

1. **01-ARCHITECTURE-OVERVIEW.md** - 30 min
2. **02-AGENT-LOOP-DETAILED.md** - 2 hrs
3. **03-HOOK-SYSTEM.md** - 2 hrs
4. **04-SESSION-ARCHITECTURE.md** - 2 hrs
5. **05-TOOL-EXECUTION.md** - 2 hrs
6. **06-AGENTHARNESS-REFERENCE.md** - 2 hrs
7. **07-DATA-FLOW-STATE.md** - 2 hrs
8. **08-LEARNING-PATH.md** - Follow implementation guide
9. **Read source files** - `src/agent.ts`, `src/agent-loop.ts`, etc.

---

## 🏗️ Architecture Overview

```
┌───────────────────────────────────────────────────────────────────────────────┐
│                           APPLICATION LAYER                                    │
│  ┌──────────────┐    ┌──────────────────┐    ┌──────────────────────────┐    │
│  │   Agent      │    │  AgentHarness    │    │     Your Custom App      │    │
│  │  (Core)      │    │  (High-Level)    │    │                          │    │
│  └───────┬──────┘    └────────┬─────────┘    └───────────┬──────────────┘    │
└──────────┼─────────────────────┼──────────────────────────┼──────────────────┘
           │                     │                          │
           ▼                     ▼                          ▼
┌───────────────────┐  ┌─────────────────────┐  ┌───────────────────────────┐
│   Agent Core      │  │   Session System    │  │      Tool System          │
│  • agent-loop.ts  │  │  • session/         │  │  • tools/                 │
│  • agent.ts       │  │  • compaction/      │  │  • bash.ts                │
│  • types.ts       │  │  • session.ts       │  │  • read.ts                │
└─────────┬─────────┘  └──────────┬──────────┘  │  • write.ts               │
          │                        │             │  • edit.ts                │
          ▼                        ▼             └──────────┬──────────────┘
┌───────────────────────────────────────────────────────────┼──────────────────┐
│                    AGENT CORE LAYER                        │                  │
│  • Async iteration                                         │                  │
│  • Event streaming                                         │                  │
│  • Hook execution                                          │                  │
│  • Tool execution                                          │                  │
└────────────────────────────────────────────────────────────┴──────────────────┘
```

---

## 🔑 Key Concepts

### 1. Agent Core

- **Low-level** async iteration
- **Message-based** communication
- **Event-driven** state changes
- **Hook system** for customization

### 2. AgentHarness

- **High-level** API
- **Session persistence** (tree structure)
- **Branching** support
- **Context compaction**
- **Tool context binding**

### 3. Hooks

- **Before/after** tool execution
- **Message transformation**
- **Context manipulation**
- **Queue draining**

### 4. Session Tree

- **Persistent** conversation history
- **Branchable** conversation paths
- **Context building** from tree
- **Compaction** for efficiency

---

## 🎓 How to Use This Guide

### For Top-Down Learning

1. Start with **01-ARCHITECTURE-OVERVIEW.md**
2. Study **09-DIAGRAMS.md** for visual understanding
3. Read **02-AGENT-LOOP-DETAILED.md** for core implementation
4. Explore **03-HOOK-SYSTEM.md** for customization
5. Understand **04-SESSION-ARCHITECTURE.md** for persistence

### For Quick Start

1. Read **10-QUICK-START.md**
2. Use **11-COMPLETE-SUMMARY.md** as reference
3. Implement while referencing other docs

### For Deep Dive

1. Follow the learning path in **08-LEARNING-PATH.md**
2. Read source files alongside documentation
3. Implement incrementally
4. Test each component

---

## 📝 Implementation Checklist

### Phase 1: Data Types (Julia)
- [ ] AgentMessage type
- [ ] AgentEvent types
- [ ] AgentTool interface
- [ ] AgentContext
- [ ] AgentState

### Phase 2: Core Agent
- [ ] Agent class
- [ ] State management
- [ ] Event streaming
- [ ] Queue management

### Phase 3: Agent Loop
- [ ] `runAgentLoop()`
- [ ] `streamAssistantResponse()`
- [ ] `executeToolCalls()`
- [ ] `prepareToolCall()`
- [ ] Event emission

### Phase 4: Hooks
- [ ] Hook registration
- [ ] Hook execution
- [ ] Return value handling

### Phase 5: Session
- [ ] Tree structure
- [ ] Entry types
- [ ] Context building
- [ ] Persistence

### Phase 6: AgentHarness
- [ ] High-level API
- [ ] Queue methods
- [ ] Branching
- [ ] Compaction

---

## 🛠️ Recommended Implementation Order

1. **Data Types** - Define all types in Julia
2. **Core Agent** - Implement Agent class with basic state
3. **Event System** - Implement event streaming
4. **Agent Loop** - Implement the main loop
5. **Tool System** - Implement tool execution
6. **Hooks** - Add hook system
7. **Session** - Implement session persistence
8. **Harness** - Add high-level API

---

## 📚 Related Files

- `packages/agent/src/` - Source files
  - `agent.ts` - Agent class
  - `agent-loop.ts` - Core loop
  - `types.ts` - Type definitions
  - `proxy.ts` - Proxy utilities
  - `stream-fn.ts` - Default stream function
  - `harness/` - Harness implementation

---

## 💡 Tips

### For Julia Implementation

1. **Start simple** - Implement basic types first
2. **Test incrementally** - Test each component
3. **Follow patterns** - Use Julia's type system
4. **Use idioms** - Follow Julia conventions
5. **Refer to docs** - Use this guide as reference

### Common Patterns

- **Event-driven** - Use Julia's event system
- **Immutable data** - Prefer immutable structures
- **Multiple dispatch** - Leverage Julia's dispatch
- **Async/await** - Use Julia's async for streaming

---

## 🎯 Success Criteria

After learning, you should be able to:

✅ Explain the two-layer architecture  
✅ Trace a message through the system  
✅ Identify when each hook is called  
✅ Explain how session persistence works  
✅ Describe the tool execution flow  
✅ Implement a custom tool  
✅ Create a conversation branch  
✅ Compress conversation history  

---

## 📞 Getting Help

- Read the documentation files
- Check the diagrams for visual understanding
- Follow the learning path for structured learning
- Refer to the complete summary for reference

---

**Happy Learning! 🚀**

Start with **01-ARCHITECTURE-OVERVIEW.md** and **09-DIAGRAMS.md** for the big picture.