diff --git a/packages/ipuaro/README.md b/packages/ipuaro/README.md index ded5b8d..2d25a88 100644 --- a/packages/ipuaro/README.md +++ b/packages/ipuaro/README.md @@ -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)