update
This commit is contained in:
@@ -0,0 +1,270 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user