Skip to content

chore: update README for clarity and consistency; redact sensitive AP… #57

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 27, 2025
Merged

chore: update README for clarity and consistency; redact sensitive AP… #57

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
325 changes: 160 additions & 165 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,219 +1,214 @@
# 🚀 Agentic - Production-Ready TUI Framework
# Agentic

[![Rust CI](https://github.com/gitcoder89431/agentic/actions/workflows/rust.yml/badge.svg)](https://github.com/gitcoder89431/agentic/actions/workflows/rust.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
```
█████╗ ██████╗ ███████╗███╗ ██╗████████╗██╗ ██████╗
██╔══██╗██╔════╝ ██╔════╝████╗ ██║╚══██╔══╝██║██╔════╝
███████║██║ ███╗█████╗ ██╔██╗ ██║ ██║ ██║██║
██╔══██║██║ ██║██╔══╝ ██║╚██╗██║ ██║ ██║██║
██║ ██║╚██████╔╝███████╗██║ ╚████║ ██║ ██║╚██████╗
╚═╝ ╚═╝ ╚═════╝ ╚══════╝╚═╝ ╚═══╝ ╚═╝ ╚═╝ ╚═════╝
```

> **Version:** 0.1.0
> **Status:** Production Ready ✅
[![Build Status](https://github.com/gitcoder89431/agentic/workflows/CI/badge.svg)](https://github.com/gitcoder89431/agentic/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Crate](https://img.shields.io/crates/v/agentic.svg)](https://crates.io/crates/agentic)

A beautiful, responsive terminal user interface (TUI) application built with modern Rust architecture. Features Everforest theming, Taffy flexbox layouts, and comprehensive event handling.
**Agentic :: The agent you work WITH**
**AI Model Orchestrator & Agent Framework**

## 🎨 Features
<!-- GIF Demo placeholder - add your demo GIF here -->
![Demo](demo.gif)

- **🌲 Everforest Theme System**: Dark/Light theme variants with runtime switching
- **📐 Responsive Layouts**: Taffy-powered flexbox-style layout engine
- **⚡ Event-Driven Architecture**: Clean async/await with proper state management
- **🔧 Production Ready**: Comprehensive CI/CD pipeline with quality gates
- **🎯 Zero Dependencies**: Minimal, focused dependency tree
- **✨ Beautiful ASCII Art**: Elegant logo with centered presentation
## Core Philosophy

## 🚀 Quick Start
Agentic transforms the typical command-response dynamic into true collaboration. Instead of barking orders at an AI, you work together through thoughtful query refinement and synthesis. Our "Karesansui" design philosophy creates a zen garden of computational thought - clean, minimalist, and purposeful. Every interaction flows like carefully placed stones in sand, building toward profound understanding rather than quick answers.

### Prerequisites
## Key Features

- **Rust 1.70+** (tested with latest stable)
- **Terminal** with true color support recommended
• **Collaborative Query Refinement** via a Local AI Orchestrator
• **Seamless Integration** with Powerful Cloud Models (via OpenRouter)
• **Minimalist, Keyboard-Driven** "Zen Garden" TUI
• **Creates Structured, "Atomic Notes"** (Markdown + YAML) for your Knowledge Base
• **Built in Rust** 🦀 for a Fast, Native Experience

### Installation & Running
## Installation

```bash
# Clone the repository
git clone https://github.com/gitcoder89431/agentic.git
cd agentic
### Download Release Binaries

# Run the application
cargo run

# Or build for release
cargo build --release
./target/release/agentic
**macOS (Intel/Apple Silicon)**
```bash
curl -L https://github.com/gitcoder89431/agentic/releases/download/v0.1.0/agentic-macos.tar.gz | tar xz
sudo mv agentic /usr/local/bin/
```

### Controls

- **ESC / q**: Quit application
- **t / T**: Toggle between Dark/Light themes
- **Ctrl+C**: Force quit with signal handling
- **Terminal Resize**: Automatic layout recalculation

## 🛠️ Development

### Local Development

Before pushing changes, run these checks locally:

**Linux (x86_64)**
```bash
# Format code
cargo fmt

# Check formatting
cargo fmt --check

# Run lints
cargo clippy -- -D warnings

# Run tests
cargo test

# Check compilation
cargo check
curl -L https://github.com/gitcoder89431/agentic/releases/download/v0.1.0/agentic-linux.tar.gz | tar xz
sudo mv agentic /usr/local/bin/
```

### 🔧 CI/CD Pipeline
**Windows**
```powershell
# Download from releases page and add to PATH
# https://github.com/gitcoder89431/agentic/releases/download/v0.1.0/agentic-windows.zip
```

Our GitHub Actions CI pipeline ensures code quality with multiple validation layers:
### Build from Source
```bash
git clone https://github.com/gitcoder89431/agentic.git
cd agentic
cargo build --release
./target/release/agentic-tui
```

#### Pipeline Jobs
## Configuration

1. **🏗️ Build & Test** (`build_and_test`)
- Code formatting validation (`cargo fmt --check`)
- Lint checking with zero warnings (`cargo clippy -- -D warnings`)
- Compilation verification (`cargo build --verbose`)
- Test suite execution (`cargo test --verbose`)
⚠️ **Important**: Agentic requires **BOTH** a local AI model (for query orchestration) and a cloud model (for synthesis) to function. The local model privately refines your questions, then the cloud model creates the final insights.

2. **🛡️ Security Audit** (`security_audit`)
- Vulnerability scanning with `cargo audit`
- Checks for known security issues in dependencies
### Complete Setup Guide

3. **📦 Dependency Check** (`check_dependencies`)
- Validates dependency freshness with `cargo outdated`
- Ensures we're using up-to-date packages
Follow these steps in order - you need both components:

#### Trigger Conditions
#### Step 1: Local AI Setup (Required)

- **Pushes to `main`**: Full pipeline execution
- **Pull Requests**: All jobs run before merge approval
- **Manual triggers**: Available via GitHub Actions UI
1. **Install Ollama** (Free, runs on your computer)
```bash
# macOS
brew install ollama

# Or download from: https://ollama.ai
```

#### Performance Optimizations
2. **Download a Local Model**
```bash
# Start Ollama service
ollama serve

# In another terminal, pull a model (this may take a few minutes)
ollama pull llama3.2:3b # Good balance of speed/quality
# or
ollama pull qwen2.5:7b # Higher quality, needs more RAM
```

- **Cargo Registry Cache**: Speeds up dependency downloads
- **Target Directory Cache**: Accelerates compilation
- **Hash-Based Invalidation**: Efficient cache management with `Cargo.lock`
3. **Configure in Agentic**
- In Settings, set "Local Endpoint" to `localhost:11434`
- Select your downloaded model from the list
- This handles initial query refinement privately on your machine

#### Common Failure Scenarios & Fixes
#### Step 2: Cloud Setup (Required)

| Error | Cause | Fix |
|-------|-------|-----|
| `cargo fmt --check failed` | Inconsistent formatting | Run `cargo fmt` locally |
| `cargo clippy warnings` | Lint violations | Fix warnings or use `#[allow(...)]` |
| `tests failed` | Broken functionality | Fix failing tests |
| `security vulnerabilities` | Outdated dependencies | Run `cargo audit fix` |
1. **Get an OpenRouter Account**
- Visit [openrouter.ai](https://openrouter.ai) and sign up (takes 2 minutes)
- Generate an API key from your dashboard
- Add $5-10 credit OR use free models (see guide below)

### 🏗️ Architecture
2. **Configure in Agentic**
- Run `agentic` in your terminal
- Press `s` to open Settings
- Navigate to "Cloud API Key" and paste your OpenRouter key
- Browse available models and select one (see model selection guide below)
- Press `s` to save

```
┌─────────────────────────────────────────────────────────┐
│ AGENTIC TUI │
├─────────────────────────────────────────────────────────┤
│ Event System │ Theme Engine │ Layout Engine │
│ ────────────── │ ───────────── │ ───────────── │
│ • AppEvent │ • Everforest │ • Taffy 3-Layer │
│ • AppState │ • Dark/Light │ • Header/Body │
│ • Async Runtime │ • Runtime Switch│ • Footer/Flex │
├─────────────────────────────────────────────────────────┤
│ Ratatui Core │
│ Crossterm Backend │
└─────────────────────────────────────────────────────────┘
```
### 🎯 Model Selection Guide

### 📁 Project Structure
When choosing a cloud model in Agentic's settings, look for these indicators:

```
agentic/
├── .github/workflows/ # CI/CD pipeline configuration
├── src/
│ ├── events.rs # Event handling & state management
│ ├── layout.rs # Taffy flexbox layout engine
│ ├── theme.rs # Everforest theme system
│ ├── ui/ # User interface components
│ │ ├── app.rs # Main application logic
│ │ └── mod.rs # UI module declarations
│ ├── lib.rs # Library root
│ └── main.rs # Application entry point
├── examples/ # Demo applications
├── Cargo.toml # Project dependencies
└── README.md # Project documentation
```
**💰 Cost Structure:**
- Models with `:free` suffix = Completely free (perfect for learning)
- Models with pricing = Pay per token (~$0.50-10 per 1M tokens)
- Check the "pricing" column to see prompt/completion costs

## 🧪 Testing
**🧠 Model Types:**
- Look for `:instruct` or `:chat` in the name = Good for conversations (what you want)
- Avoid `:base` models = Raw models without instruction training
- Avoid `:embed` models = For embeddings only, not chat

### Unit Tests
**📏 Context Length:**
- 4k-8k tokens = Good for short conversations
- 32k-128k tokens = Better for longer discussions
- 1M+ tokens = Can handle very long contexts (costs more)

```bash
# Run all tests
cargo test
**🏷️ Model Families:**
- `anthropic/claude-*` = Excellent reasoning and safety
- `openai/gpt-*` = Well-rounded performance
- `meta-llama/*` = Open source, good quality
- `google/gemini-*` = Strong at analysis and coding
- `deepseek/*` = Often have free versions available

# Run tests with output
cargo test -- --nocapture
**💡 Beginner Tips:**
- Start with any `:free` model to test the system
- If you have credits, try `anthropic/claude-3.5-sonnet` for quality
- Higher context length = more expensive but can handle longer discussions
- The model list updates frequently - newer models often perform better

# Run specific test
cargo test test_name
```
#### Step 3: Ready to Collaborate!

### Manual Testing
- Type your question naturally
- Watch the local model orchestrate thoughtful proposals
- Choose a proposal for the cloud model to synthesize
- Save the resulting "atomic note" to your knowledge base
- **Files are automatically saved** to `~/Documents/ruixen/` as Markdown with YAML metadata

```bash
# Theme demo
cargo run --example theme_demo
### Why Both Models?

# Layout demo
cargo run --example layout_demo
The **local model** (Ollama) handles query orchestration privately on your machine, while the **cloud model** (OpenRouter) provides powerful synthesis capabilities. This hybrid approach gives you both privacy and cutting-edge AI performance!

# Input handling demo
cargo run --example issue_4_demo
```
### Troubleshooting

## 📦 Dependencies
**"Local endpoint not accessible"**
- Make sure Ollama is running: `ollama serve`
- Check the endpoint in settings: `localhost:11434`

### Core Dependencies
- **ratatui** (0.27): Terminal UI framework
- **crossterm** (0.27): Cross-platform terminal handling
- **tokio** (1.0): Async runtime
- **taffy** (0.4): Flexbox layout engine
**"OpenRouter API key invalid"**
- Verify your key starts with `sk-or-v1-`
- Check you have credits or selected a free model

### Development Dependencies
- **GitHub Actions**: Automated CI/CD
- **cargo-audit**: Security vulnerability scanning
- **cargo-outdated**: Dependency freshness checks
**"Model not found"**
- For local: ensure model is downloaded with `ollama list`
- For cloud: verify model name exactly matches OpenRouter's list

## Usage

**Navigation**
- `Tab/Shift+Tab` - Navigate between UI elements
- `↑/↓ or j/k` - Move through lists and proposals
- `Enter` - Select/Confirm actions
- `Esc` - Return to previous screen
- `q` - Quit application

**Slash Commands**
- `/settings` - Open configuration modal
- `/about` - View application information
- `/quit` - Exit the application

**Key Bindings**
- `s` - Quick access to Settings
- `a` - Quick access to About
- `Left/Right` - Scroll through About page content

## 🤝 Contributing
## Architecture

1. **Fork** the repository
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **Run** local checks (`cargo fmt && cargo clippy && cargo test`)
4. **Commit** changes (`git commit -m 'Add amazing feature'`)
5. **Push** to branch (`git push origin feature/amazing-feature`)
6. **Open** a Pull Request
Agentic follows the RuixenOS workspace architecture:

### Pull Request Process
```
agentic/
├── crates/
│ ├── agentic-core/ # The "motor" - reusable AI logic
│ ├── agentic-tui/ # The "drill" - terminal interface
│ └── starlit-gui/ # Future graphical interface
└── Cargo.toml # Workspace configuration
```

- ✅ All CI checks must pass (formatting, lints, tests, security)
- ✅ Code must follow Rust best practices
- ✅ Include tests for new functionality
- ✅ Update documentation as needed
This modular design allows the same AI capabilities to power multiple interfaces while maintaining clean separation between logic and presentation.

## 📄 License
## License

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
MIT License - see [LICENSE](LICENSE) for details.

## 🙏 Acknowledgments
## Contributing

- **Ratatui Community** for the excellent TUI framework
- **Taffy Team** for the powerful layout engine
- **Everforest** color scheme for beautiful aesthetics
- **Rust Community** for amazing tooling and ecosystem
Built with constitutional Rust patterns and love. Issues and PRs welcome!

---

**Built with ❤️ using Rust** 🦀
*The curiosity machine doesn't just process queries - it awakens wonder.*
Loading