271 lines
9.4 KiB
Markdown
271 lines
9.4 KiB
Markdown
# 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.
|