eljay-ai 1.1.0

package/AGENTS.md

@@ -0,0 +1,57 @@
+# Project Rules
+
+This project is a **local, free Universal AI Assistant** built in Python.
+ElJay AI supports coding, web research, image generation, video generation,
+general knowledge, and general assistance through a single terminal interface.
+
+## Stack
+
+- Language: Python 3.14 (standard library only)
+- Runtime: Ollama at `http://127.0.0.1:11434`
+- Model: `qwen2.5-coder:3b` (configurable via `AGENT_MODEL`)
+- Interface: command line (`eljay` via npm global install, or `python eljay.py`)
+- Web search: DuckDuckGo Lite (free, no API key)
+
+## Hardware-awareness
+
+ElJay detects the local machine's hardware (OS, CPU, RAM, GPU, VRAM total & available,
+disk) and recommends appropriate model modes. It reports capabilities honestly
+and does not fake image/video generation when the hardware cannot support it.
+
+## Agent architecture
+
+The Main Agent routes natural-language requests to specialized agents:
+Coding, Research, Image, Video, Knowledge. Routing uses keyword matching
+(no LLM call) for speed and determinism. Image/Video agents are selected by
+keyword even when local providers are unavailable — they then report the
+setup steps or suggest free external providers.
+
+## Rules
+
+- Preserve the existing architecture: `agent/` modules, entry point `eljay.py`. `myagent.py` is a backwards-compatible alias.
+- **Do NOT add third-party dependencies.** The standard library is enough. If a
+  dependency truly seems necessary, explain why and ask first.
+- Do not rewrite working code. Prefer small, targeted changes.
+- Modify only what is necessary for the task.
+- Ask before any destructive operation (delete, git reset, git push).
+- Keep documentation (`README.md`) in sync with the implementation.
+- Verify changes before reporting completion — run the tests and say what ran.
+
+## Verification
+
+Run all tests:
+
+```powershell
+python tests/run_all.py
+```
+
+Individual test modules live in `tests/`.
+
+## Safety invariants (must not be weakened)
+
+- Tools are **read-only and `safe`** unless they write or execute.
+- All filesystem paths are confined to the project root.
+- There is **no delete/rename/move capability**.
+- Non-safe actions require explicit user confirmation; high-risk actions require
+  typing `yes`; a session `always` never bypasses `high`.
+- Command execution never uses a shell, and pipes/redirection are rejected.

package/README.md

@@ -0,0 +1,479 @@
+# ElJay AI
+
+A **free, local, terminal-based Universal AI Assistant** for Windows. It talks to
+a local LLM through [Ollama](https://ollama.com) — **no paid API keys for core
+features, no cloud, and zero third-party Python packages** (standard library only).
+
+ElJay AI can:
+
+```
+CODING            → Local Ollama model
+RESEARCH          → DuckDuckGo web search (free)
+IMAGE GENERATION  → Local (if GPU + ComfyUI/torch) or free providers
+VIDEO GENERATION  → Local (if 6 GB+ VRAM) or free providers
+GENERAL KNOWLEDGE → Local Ollama model
+GENERAL HELP      → Local Ollama model
+```
+
+The Main Agent routes natural-language requests to the appropriate specialized
+agent automatically. You do not need to specify which capability to use.
+
+```
+Windows Terminal / PowerShell
+            |
+       eljay  (a.k.a. myagent)
+            |
+     Main Agent (coordinator)
+            |
+   ┌────────┼────────┬────────┐
+   │        │        │        │
+ Coding   Research  Image   Video
+   │        │        │        │
+   └─────── Ollama ← Web     └── (local GPU or free provider)
+```
+
+## Requirements
+
+- **Windows** (PowerShell or Windows Terminal)
+- **Python 3.14** — verified (`python --version`)
+- **Ollama** — verified (`ollama --version`)
+- **Node.js 20+** — for the `npm i -g` install path (`node --version`)
+- A local model, e.g. `qwen2.5-coder:3b`
+
+> On this machine `python3` is a broken Microsoft Store stub — use `python`.
+
+## Quick start
+
+### Option A — Install via npm (global command from any folder)
+
+```powershell
+npm install -g eljay-ai
+```
+
+This installs two commands on your PATH: `eljay` and `eljay-ai`. Restart your
+terminal, then from **any** project folder:
+
+```powershell
+C:\Projects\MyProject> eljay
+```
+
+> If `npm` is not on your PATH yet, run the command from the **Node.js terminal**
+> that ships with the [Node.js installer](https://nodejs.org).
+
+### Option B — Install via install.ps1 (PowerShell)
+
+From the project directory:
+
+```powershell
+.\install.ps1        # adds the bin folder to your USER PATH
+```
+
+Restart the terminal, then:
+
+```powershell
+C:\Projects\MyProject> eljay
+```
+
+### Option C — Run directly from source
+
+```powershell
+python eljay.py
+```
+
+`myagent.py` remains as a compatibility alias that behaves identically.
+
+## Setup
+
+```powershell
+ollama serve
+ollama pull qwen2.5-coder:3b
+ollama list
+```
+
+## Running
+
+Interactive session:
+```powershell
+eljay
+python eljay.py
+```
+
+One-shot prompt:
+```powershell
+eljay "Explain how databases work"
+python eljay.py "Explain how databases work"
+eljay --version
+```
+
+## Commands (interactive)
+
+| Command | Effect |
+|---|---|
+| `/help` | Show help |
+| `/tools` | List available tools |
+| `/agents` | List specialized agents (Coding, Research, Image, Video, Knowledge, Main) |
+| `/skills` | List loaded skills |
+| `/knowledge [query]` | Search knowledge entries |
+| `/providers` | Show provider availability |
+| `/status` | Show hardware, model, agents, tools, skills, knowledge |
+| `/verify` | Show the project's test/build commands |
+| `/memory` | Show local memory (`/memory clear` erases it) |
+| `/permissions` | Show risk levels + session allowances (`/permissions reset` clears) |
+| `/clear` | Forget the conversation |
+| `/model [name]` | Show or switch the active model |
+| `/exit`, `/quit` | Leave the agent |
+
+## Capabilities
+
+### Coding Agent
+
+Inspects projects, reads files, searches code, makes confirmed edits, runs
+commands, tests, verifies changes, and reports git status.
+
+**Workflow:** `Inspect → Understand → Propose → Permission → Modify → Verify`
+
+Never claims success without actual tool evidence.
+
+### Research Agent
+
+Searches the web via DuckDuckGo Lite, fetches pages, extracts content,
+compares sources, and summarizes with citation.
+
+**Source hierarchy:** Official docs → Primary sources → Reliable technical
+sources → Reputable secondary sources.
+
+### Image Agent
+
+Handles image generation requests. Reports which provider/model was used.
+If no provider is available, gives exact setup steps.
+
+### Video Agent
+
+Handles video generation requests. Reports hardware requirements honestly.
+If generation is unavailable, describes the concept and the setup needed.
+
+### Knowledge Agent
+
+General conversation, explanations, creative writing, idea generation.
+Uses the local model — no web research unless the user asks for current info.
+
+### General Assistant Behavior
+
+```
+> Hello
+> Help me write a professional email.
+> Explain quantum computing simply.
+> Fix the authentication problem in this Laravel project.
+> Research the latest Laravel documentation.
+> Generate an image of a dark gothic cowboy.
+> Create a cinematic video concept for this song.
+```
+
+You do not need to manually select an agent. ElJay determines the appropriate
+capability from your request.
+
+## Hardware-Aware Detection
+
+ElJay detects your hardware and recommends appropriate model modes:
+
+```
+High-end GPU  → large models
+Mid-range GPU → medium / quantized models
+~4 GB VRAM    → small / quantized models or CPU offloading
+Low VRAM      → CPU / system RAM where practical
+No GPU        → CPU-only mode
+```
+
+The `/status` command shows detailed hardware info including **total VRAM**
+and **currently available (free) VRAM**.
+
+### Capabilities by hardware tier
+
+| Tier | VRAM | Image | Video |
+|---|---|---|---|
+| High-end GPU | 8 GB+ | Full-precision local models | Local video generation |
+| Mid-range GPU | 4–8 GB | Medium/quantized models | Limited resolution video |
+| Low VRAM | < 4 GB | CPU offload (slow) or external | Not available locally |
+| No GPU | N/A | External provider or CPU (very slow) | External provider |
+
+## Tools
+
+| Tool | Risk | Purpose |
+|---|---|---|
+| `get_current_time` | safe | Local date/time |
+| `project_info` | safe | Name, root, detected stack |
+| `list_files` | safe | Project tree (`path`, `depth`, `max_entries`) |
+| `read_file` | safe | Numbered lines (`path`, `start_line`, `end_line`) |
+| `search_code` | safe | Find text (`query`, `path`, `regex`, `case_sensitive`, `max_results`) |
+| `detect_checks` | safe | Project's lint/test/build commands |
+| `git_status` | safe | Branch + changed files (read-only) |
+| `remember` | safe | Save a note to local memory |
+| `create_file` | **ask** | Create a NEW file (refuses to overwrite) |
+| `edit_file` | **ask** | Replace exact text in an existing file |
+| `run_command` | **ask/high** | Run ONE command (risk depends on the command) |
+
+## Permissions
+
+| Risk | Behavior |
+|---|---|
+| `safe` | Runs automatically (all read-only tools) |
+| `ask` | Shows a preview, then `[y]es / [n]o / [a]lways` |
+| `high` | Shows a preview, then requires you to TYPE `yes` |
+
+- `a` grants a **session allowance** — the agent stops asking for that tool.
+- A session allowance **never** bypasses a `high` action.
+- `run_command` is classified **per command**: allow-listed programs (`python`,
+  `npm`, `git status`, ...) are `ask`; anything else, or a dangerous pattern
+  (`rm`, `git push`, `git reset`, `npm uninstall`, `drop database`, `sudo`, ...),
+  is `high`.
+- No way to ask (non-interactive) means **deny** — it fails closed.
+
+## Safety boundaries
+
+- **No delete, rename, or move capability exists in the codebase.**
+- All filesystem paths are confined to the project root (`../` is rejected).
+- `create_file` refuses to overwrite; `edit_file` only changes exact matched text.
+- Writes are capped at 1 MB and refuse binary files; edits refuse ambiguous matches.
+- `read_file` refuses whole-file reads > 1 MB and caps output at 2000 lines.
+- Commands never use a shell: `|`, `&`, `;`, `<`, `>`, backticks and `$(...)` are
+  refused, so there is no shell-injection surface.
+- Commands run with a timeout and captured output; cwd is confined to the root.
+- The agent never commits or pushes; `git_status` runs only read-only git.
+
+## Provider Architecture
+
+ElJay uses a provider abstraction — not locked to one backend.
+
+| Provider | Capability | Cost | Requirements |
+|---|---|---|---|
+| **Ollama** | text generation | Local | Ollama installed + model pulled |
+| **DuckDuckGo** | web search | Free | Internet |
+| **Image (local)** | image generation | Local | CPU or GPU + ComfyUI/torch |
+| **Video (local)** | video generation | Local | 6 GB+ VRAM GPU |
+
+### Free-first policy
+
+```text
+LOCAL → FREE/OPEN SOURCE → FREE API → OPTIONAL PAID
+```
+
+Paid services are never mandatory for core features. When an external provider
+is used, ElJay clearly labels it as "API KEY REQUIRED" or "PAID".
+
+## Models
+
+ElJay does **not** automatically download models. If a requested model is
+unavailable, it reports what's installed and suggests the exact pull command:
+
+```text
+Model 'qwen2.5-coder:7b' is not installed.
+Available: qwen2.5-coder:3b
+Using 'qwen2.5-coder:3b' for now.
+Install with: ollama pull qwen2.5-coder:7b
+```
+
+## Skills
+
+Skills are reusable instruction bundles stored in `skills/`. They are
+dynamically loaded and only injected into the prompt when relevant to your
+request — keeping context lean.
+
+```
+skills/
+├── coding/        code review, fix attempts
+├── debugging/     root cause analysis
+├── testing/       pytest best practices
+├── react/         component best practices
+├── laravel/       authentication patterns
+├── php/           standards
+├── mysql/         performance
+├── security/      input validation
+├── research/      source tracking
+├── image-generation/
+├── video-generation/
+└── general/       communication
+```
+
+List skills with `/skills`, search with `/skills [query]`.
+
+## Knowledge Base
+
+A two-level knowledge system:
+
+- **Global knowledge** — `knowledge/` in the ElJay installation directory.
+  Reusable across all projects.
+- **Project knowledge** — `.agent/knowledge/` in the project workspace.
+  Project-specific facts.
+
+Search with `/knowledge [query]` or `search_knowledge` tool.
+
+## Memory (`.agent/`)
+
+A gitignored folder for lightweight memory:
+
+```
+.agent/config.json     agent settings
+.agent/history.json    recent conversation turns
+.agent/context.json    notes saved with the `remember` tool
+.agent/knowledge/      project-specific knowledge
+.agent/outputs/        generated images and videos
+```
+
+Notes are injected into the system prompt on startup. Inspect or erase with
+`/memory` and `/memory clear`.
+
+## Context management
+
+The agent never sends the whole project. Tools fetch only what is needed, tool
+output is capped, and the conversation is trimmed to a character budget
+(oldest turns dropped first, with a note) before each model call.
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `OLLAMA_HOST` | `http://127.0.0.1:11434` | Ollama API address |
+| `AGENT_MODEL` | `qwen2.5-coder:3b` | Model to use |
+| `AGENT_TIMEOUT` | `300` | Seconds to wait for a reply |
+| `AGENT_MAX_STEPS` | `6` | Max tool steps per turn |
+| `AGENT_MAX_CONTEXT_CHARS` | `16000` | Conversation character budget |
+| `AGENT_AUTO_APPROVE` | *(off)* | **Dangerous:** skip `ask` confirmations (never `high`) |
+
+## Project rules (`AGENTS.md`)
+
+If the project root contains `AGENTS.md`, it is loaded and injected into the system
+prompt as **binding instructions**, and the banner shows `Rules : AGENTS.md loaded`.
+
+## Testing
+
+```powershell
+python tests/run_all.py
+```
+
+| Module | Covers |
+|---|---|
+| `tests/test_agent_core.py` | tool loop, parsing, unknown-tool guard, permissions |
+| `tests/test_workspace.py` | listing, reading, search, root confinement |
+| `tests/test_edits.py` | create/edit safety, overwrite refusal, previews |
+| `tests/test_runner.py` | command classification, execution, timeout |
+| `tests/test_capabilities.py` | rules, context, memory, verification, git |
+| `tests/test_eljay.py` | rename, banner, version, launchers, package.json, provider fix |
+| `tests/test_universal.py` | hardware, router, skills, knowledge, agents, providers, tools, CLI |
+
+## Project layout
+
+```
+eljay.py               primary entry point (banner, model, dispatch)
+myagent.py             compatibility alias (imports from eljay)
+AGENTS.md              this project's rules (loaded at startup)
+install.ps1            adds bin/ to your user PATH
+package.json           npm package manifest (bin: eljay, eljay-ai)
+eljay.js               Node wrapper for `npm i -g` global install
+bin/eljay.cmd          Windows launcher
+bin/eljay              Git Bash launcher
+bin/myagent.cmd        Windows launcher (compat alias)
+bin/myagent            Git Bash launcher (compat alias)
+agent/config.py        configuration + system prompt
+agent/ollama_client.py stdlib Ollama HTTP client
+agent/chat.py          terminal UI, /commands, permission prompt
+agent/agent.py         AgentCore: reason -> act -> observe loop
+agent/tools.py         Tool + ToolRegistry (schema, risk, preview)
+agent/permissions.py   safe / ask / high gate + session allowances
+agent/workspace.py     root/stack detection, listing, reading, searching
+agent/edits.py         file creation + exact-match editing (only writer)
+agent/runner.py        command classification + execution
+agent/verification.py  detect the smallest useful check
+agent/rules.py         AGENTS.md loading
+agent/context.py       conversation trimming
+agent/memory.py        .agent/ history + notes
+agent/gitaware.py      read-only git inspection
+agent/builtin_tools.py tool registration
+agent/hardware.py      hardware detection (GPU, VRAM, RAM, disk)
+agent/router.py        agent routing and orchestration
+agent/providers/       provider architecture (ollama, web, image, video)
+agent/agents/registry.py  agent routing (Main, Coding, Research, ...)
+agent/skills.py        skills discovery framework
+agent/knowledge.py     project-local + global knowledge base
+skills/                default skill bundles
+knowledge/             global knowledge entries
+tests/                 deterministic tests (no model, no network)
+```
+
+## Architecture notes
+
+### Agent types
+
+| Agent | Purpose |
+|---|---|
+| `Main` | Coordinator — handles general conversation, routes to specialists |
+| `Coding` | Code understanding and editing |
+| `Research` | Web search and information gathering |
+| `Image` | Image generation (reports availability, suggests setup) |
+| `Video` | Video generation (reports hardware requirements honestly) |
+| `Knowledge` | General knowledge, explanations, creative writing |
+
+### Providers
+
+- **Ollama** — text generation via local LLMs
+- **Web** — DuckDuckGo Lite search (truly free, no API key)
+- **Image** — detects local tooling; reports clearly when unavailable
+- **Video** — detects local tooling; reports hardware requirements honestly
+
+### Hardware-aware behavior
+
+```text
+High-end GPU  → Use appropriate larger models
+Mid-range GPU → Use medium/quantized models
+4 GB VRAM     → Use small/quantized models or CPU/offloading
+Low VRAM      → Use CPU / system RAM where practical
+No GPU        → CPU-only mode
+```
+
+### Data privacy
+
+```text
+Local Ollama  → stays local
+Web research  → internet (DuckDuckGo)
+Image provider → prompt may leave machine (if external provider used)
+Video provider → prompt/media may leave machine (if external provider used)
+```
+
+ElJay never sends user data externally without the provider being explicitly
+configured and used.
+
+### Extensibility
+
+ElJay is designed so you can add new capabilities later without rewriting:
+
+- **New agent**: Add to `agent/agents/registry.py`
+- **New provider**: Create in `agent/providers/` and register in `PROVIDERS`
+- **New skill**: Add a `.md` file in `skills/<category>/`
+- **New knowledge**: Add a `.md` file in `knowledge/<category>/` or `.agent/knowledge/`
+
+## Compatibility
+
+- `myagent` and `myagent.py` are kept as backward-compatible aliases.
+- All launchers in `bin/` delegate to `eljay.py`.
+
+## Troubleshooting
+
+- **`Could not reach Ollama ...`** — start it: `ollama serve`.
+- **`No Ollama models are installed`** — `ollama pull qwen2.5-coder:3b`.
+- **`python3: Python was not found`** — use `python`.
+- **The model picks the wrong tool or over-triggers** — this is a small-model
+  limitation. A larger model decides better and needs no code changes:
+  `ollama pull qwen2.5-coder:7b` and set `AGENT_MODEL=qwen2.5-coder:7b`.
+- **`ERROR: shell operators ... are not allowed`** — run one command, no pipes.
+- **Image/video generation not available** — ElJay detects your hardware and
+  reports honestly. On a GPU-less machine, local image/video generation requires
+  installing additional packages (torch, diffusers, ComfyUI) and is not bundled.
+  ElJay suggests the exact setup steps or external free providers.
+
+## Limitations
+
+- This machine has **no GPU** → local image and video generation require
+  additional packages not installed here. ElJay reports this clearly.
+- `qwen2.5-coder:7b` is the preferred model but is **not installed** — ElJay
+  defaults to `:3b` and suggests `ollama pull qwen2.5-coder:7b` if needed.
+- Web research uses DuckDuckGo Lite — may be rate-limited or blocked in some
+  environments.

package/agent/__init__.py

@@ -0,0 +1,10 @@
+"""ElJay AI — a free, local, universal AI assistant.
+
+Version 1.1.0 transforms the coding agent into a universal assistant with
+agent routing (Coding, Research, Image, Video, Knowledge), skills system,
+knowledge base, and hardware detection.
+
+This module provides the package version string.
+"""
+
+__version__ = "1.1.0"