ailabs/puaros
1
0
Fork 0
mirror of https://github.com/samiyev/puaros.git synced 2025-12-27 23:06:54 +05:00
Code Issues Packages Projects Releases Wiki Activity

docs(ipuaro): improve README with detailed documentation

Browse Source
This commit is contained in:
imfozilbek
2025-11-29 23:19:56 +05:00
parent 130a8c4f24
commit 127c7e2185
1 changed files with 214 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

274
packages/ipuaro/README.md
View File

@@ -1,17 +1,75 @@
# @samiyev/ipuaro
# @samiyev/ipuaro 🎩
Local AI agent for codebase operations with "infinite" context feeling through lazy loading.
**Local AI Agent for Codebase Operations**
## Features
"Infinite" context feeling through lazy loading - work with your entire codebase using local LLM.
- 18 LLM tools for code operations (read, edit, search, analysis, git, run)
- Redis persistence with AOF for durability
[![npm version](https://badge.fury.io/js/@samiyev%2Fipuaro.svg)](https://www.npmjs.com/package/@samiyev/ipuaro)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
> **Status:** 🚧 Early Development (v0.1.0 Foundation)
>
> Core infrastructure is ready. Active development in progress.
## Vision
Work with codebases of any size using local AI:
- 📂 **Lazy Loading**: Load code on-demand, not all at once
- 🧠 **Smart Context**: AST-based understanding of your code structure
- 🔒 **100% Local**: Your code never leaves your machine
- ⚡ **Fast**: Redis persistence + tree-sitter parsing
## Planned Features
### 18 LLM Tools
| Category | Tools | Status |
|----------|-------|--------|
| **Read** | `get_lines`, `get_function`, `get_class`, `get_structure` | 🔜 v0.5.0 |
| **Edit** | `edit_lines`, `create_file`, `delete_file` | 🔜 v0.6.0 |
| **Search** | `find_references`, `find_definition` | 🔜 v0.7.0 |
| **Analysis** | `get_dependencies`, `get_dependents`, `get_complexity`, `get_todos` | 🔜 v0.8.0 |
| **Git** | `git_status`, `git_diff`, `git_commit` | 🔜 v0.9.0 |
| **Run** | `run_command`, `run_tests` | 🔜 v0.9.0 |
### Terminal UI
```
┌─ ipuaro ──────────────────────────────────────────────────┐
│ [ctx: 12%] [project: myapp] [main] [47m] ✓ Ready │
├───────────────────────────────────────────────────────────┤
│ You: How does the authentication flow work? │
│ │
│ Assistant: Let me analyze the auth module... │
│ [get_structure src/auth/] │
│ [get_function src/auth/service.ts login] │
│ │
│ The authentication flow works as follows: │
│ 1. User calls POST /auth/login │
│ 2. AuthService.login() validates credentials... │
│ │
│ ⏱ 3.2s │ 1,247 tokens │ 2 tool calls │
├───────────────────────────────────────────────────────────┤
│ > _ │
└───────────────────────────────────────────────────────────┘
```
### Key Capabilities
🔍 **Smart Code Understanding**
- tree-sitter AST parsing (TypeScript, JavaScript)
- Ollama LLM integration (local, private)
- File watching for live index updates
- Session and undo management
- Security (blacklist/whitelist for shell commands)
- Terminal UI with Ink/React
- Symbol index for fast lookups
- Dependency graph analysis
💾 **Persistent Sessions**
- Redis storage with AOF persistence
- Session history across restarts
- Undo stack for file changes
🛡️ **Security**
- Command blacklist (dangerous operations blocked)
- Command whitelist (safe commands auto-approved)
- Path validation (no access outside project)
## Installation
@@ -23,24 +81,47 @@ pnpm add @samiyev/ipuaro
## Requirements
- Node.js >= 20.0.0
- Redis server (for persistence)
- Ollama (for LLM inference)
- **Node.js** >= 20.0.0
- **Redis** (for persistence)
- **Ollama** (for local LLM inference)
## Quick Start
### Setup Ollama
```bash
# Start in current directory
# Install Ollama (macOS)
brew install ollama
# Start Ollama
ollama serve
# Pull recommended model
ollama pull qwen2.5-coder:7b-instruct
```
### Setup Redis
```bash
# Install Redis (macOS)
brew install redis
# Start Redis with persistence
redis-server --appendonly yes
```
## Usage
```bash
# Start ipuaro in current directory
ipuaro
# Start in specific directory
ipuaro /path/to/project
# With auto-apply mode
ipuaro --auto-apply
# With custom model
ipuaro --model qwen2.5-coder:32b-instruct
# With auto-apply mode (skip edit confirmations)
ipuaro --auto-apply
```
## Commands
@@ -48,7 +129,7 @@ ipuaro --model qwen2.5-coder:32b-instruct
| Command | Description |
|---------|-------------|
| `ipuaro [path]` | Start TUI in directory |
| `ipuaro init` | Create .ipuaro.json config |
| `ipuaro init` | Create `.ipuaro.json` config |
| `ipuaro index` | Index project without TUI |
## Configuration
@@ -65,6 +146,9 @@ Create `.ipuaro.json` in your project root:
"model": "qwen2.5-coder:7b-instruct",
"temperature": 0.1
},
"project": {
"ignorePatterns": ["node_modules", "dist", ".git"]
},
"edit": {
"autoApply": false
}
@@ -76,55 +160,125 @@ Create `.ipuaro.json` in your project root:
Clean Architecture with clear separation:
```
src/
├── domain/ # Business logic (entities, value objects, interfaces)
├── application/ # Use cases, DTOs, orchestration
├── infrastructure/ # External implementations (Redis, Ollama, tools)
├── tui/ # Terminal UI (Ink/React components)
├── cli/ # CLI commands
└── shared/ # Cross-cutting concerns
@samiyev/ipuaro/
├── domain/ # Business logic (no dependencies)
│ ├── entities/ # Session, Project
│ ├── value-objects/ # FileData, FileAST, ChatMessage, etc.
│ └── services/ # IStorage, ILLMClient, ITool, IIndexer
├── application/ # Use cases & orchestration
│ ├── use-cases/ # StartSession, HandleMessage, etc.
│ └── interfaces/ # IToolRegistry
├── infrastructure/ # External implementations
│ ├── storage/ # Redis client & storage
│ ├── llm/ # Ollama client & prompts
│ ├── indexer/ # File scanner, AST parser
│ └── tools/ # 18 tool implementations
├── tui/ # Terminal UI (Ink/React)
│ └── components/ # StatusBar, Chat, Input, etc.
├── cli/ # CLI entry point
└── shared/ # Config, errors, utils
```
## Tools (18 total)
| Category | Tool | Description |
|----------|------|-------------|
| **Read** | `get_lines` | Get file lines |
| | `get_function` | Get function by name |
| | `get_class` | Get class by name |
| | `get_structure` | Get project tree |
| **Edit** | `edit_lines` | Replace lines |
| | `create_file` | Create new file |
| | `delete_file` | Delete file |
| **Search** | `find_references` | Find symbol usages |
| | `find_definition` | Find symbol definition |
| **Analysis** | `get_dependencies` | File imports |
| | `get_dependents` | Files importing this |
| | `get_complexity` | Complexity metrics |
| | `get_todos` | Find TODO/FIXME |
| **Git** | `git_status` | Repository status |
| | `git_diff` | Uncommitted changes |
| | `git_commit` | Create commit |
| **Run** | `run_command` | Execute shell command |
| | `run_tests` | Run test suite |
## Development Status
Currently at version **0.1.0** (Foundation). See [ROADMAP.md](./ROADMAP.md) for full development plan.
### ✅ Completed (v0.1.0)
### Completed
- [x] Project setup (tsup, vitest, ESM)
- [x] Domain entities (Session, Project)
- [x] Value objects (FileData, FileAST, ChatMessage, etc.)
- [x] Service interfaces (IStorage, ILLMClient, ITool, IIndexer)
- [x] Shared module (Config, Errors, Utils)
- [x] CLI placeholder commands
- [x] 91 unit tests, 100% coverage
- [x] 0.1.1 Project Setup
- [x] 0.1.2 Domain Value Objects
- [x] 0.1.3 Domain Services Interfaces
- [x] 0.1.4 Shared Config
### 🔜 Next Up
### Next
- [ ] **v0.2.0** - Redis Storage
- [ ] **v0.3.0** - Indexer (file scanning, AST parsing)
- [ ] **v0.4.0** - LLM Integration (Ollama)
- [ ] **v0.5.0-0.9.0** - Tools implementation
- [ ] **v0.10.0** - Session management
- [ ] **v0.11.0** - TUI
- [ ] 0.2.0 Redis Storage
- [ ] 0.3.0 Indexer
- [ ] 0.4.0 LLM Integration
See [ROADMAP.md](./ROADMAP.md) for detailed development plan.
## API (Coming Soon)
```typescript
import { startSession, handleMessage } from "@samiyev/ipuaro"
// Start a session
const session = await startSession({
projectPath: "./my-project",
model: "qwen2.5-coder:7b-instruct"
})
// Send a message
const response = await handleMessage(session, "Explain the auth flow")
console.log(response.content)
console.log(`Tokens: ${response.stats.tokens}`)
console.log(`Tool calls: ${response.stats.toolCalls}`)
```
## How It Works
### Lazy Loading Context
Instead of loading entire codebase into context:
```
Traditional approach:
├── Load all files → 500k tokens → ❌ Exceeds context window
ipuaro approach:
├── Load project structure → 2k tokens
├── Load AST metadata → 10k tokens
├── On demand: get_function("auth.ts", "login") → 200 tokens
├── Total: ~12k tokens → ✅ Fits in context
```
### Tool-Based Code Access
```
User: "How does user creation work?"
ipuaro:
1. [get_structure src/] → sees user/ folder
2. [get_function src/user/service.ts createUser] → gets function code
3. [find_references createUser] → finds all usages
4. Synthesizes answer with specific code context
```
## Contributing
Contributions welcome! This project is in early development.
```bash
# Clone
git clone https://github.com/samiyev/puaros.git
cd puaros/packages/ipuaro
# Install
pnpm install
# Build
pnpm build
# Test
pnpm test:run
# Coverage
pnpm test:coverage
```
## License
MIT
MIT © Fozilbek Samiyev
## Links
- [GitHub Repository](https://github.com/samiyev/puaros/tree/main/packages/ipuaro)
- [Issues](https://github.com/samiyev/puaros/issues)
- [Changelog](./CHANGELOG.md)
- [Roadmap](./ROADMAP.md)