eljay-ai 1.1.0

package/eljay.py

@@ -0,0 +1,150 @@
+"""ElJay AI — local AI coding agent entry point.
+
+Usage:
+    python eljay.py                 start an interactive chat session
+    python eljay.py "your prompt"   send a single prompt and exit
+
+`myagent.py` is kept as a compatibility alias that delegates here.
+"""
+
+import sys
+from pathlib import Path
+
+from agent import __version__, config
+from agent.agent import AgentCore
+from agent.builtin_tools import register_builtin_tools
+from agent.chat import BANNER, ask_permission, ensure_utf8, run_chat, run_once
+from agent.gitaware import branch, changed_files, is_git_repo
+from agent.hardware import detect_hardware, summarize_hardware
+from agent.knowledge import KnowledgeBase
+from agent.memory import Memory
+from agent.ollama_client import OllamaClient, OllamaError
+from agent.permissions import PermissionPolicy
+from agent.router import AgentRouter
+from agent.rules import build_system_prompt, load_rules
+from agent.skills import Skills
+from agent.tools import ToolRegistry
+from agent.workspace import Workspace, find_project_root
+
+
+def resolve_model(client: OllamaClient) -> str:
+    """Pick the model to use, verifying it is actually installed."""
+    try:
+        available = client.list_models()
+    except OllamaError as exc:
+        print(f"[error] {exc}")
+        raise SystemExit(1)
+
+    if not available:
+        print(
+            "[error] No Ollama models are installed.\n"
+            "        Install one, for example:  ollama pull qwen2.5-coder:3b"
+        )
+        raise SystemExit(1)
+
+    if config.DEFAULT_MODEL in available:
+        return config.DEFAULT_MODEL
+
+    # Requested model is missing — tell the user rather than silently swapping.
+    print(
+        f"[warn] Model '{config.DEFAULT_MODEL}' is not installed.\n"
+        f"       Available: {', '.join(available)}\n"
+        f"       Using '{available[0]}' for now. "
+        f"(set AGENT_MODEL to choose a different default)"
+    )
+    return available[0]
+
+
+def build_registry(workspace: Workspace, memory: Memory) -> ToolRegistry:
+    registry = ToolRegistry()
+    register_builtin_tools(registry, workspace, memory)
+    return registry
+
+
+def main() -> int:
+    # Fix console encoding before printing anything (Windows defaults to cp1252).
+    ensure_utf8()
+
+    args = sys.argv[1:]
+    if args and args[0] in ("--version", "-V"):
+        print(f"ElJay AI {__version__}")
+        return 0
+    if args and args[0] in ("--help", "-h"):
+        print("usage: eljay [\"prompt\"] | eljay --version")
+        print("Run with no arguments for an interactive session.")
+        return 0
+
+    client = OllamaClient(config.OLLAMA_HOST, timeout=config.REQUEST_TIMEOUT)
+    model = resolve_model(client)
+
+    # The project the agent works in, detected from the current directory.
+    workspace = Workspace(find_project_root(Path.cwd()))
+    memory = Memory(workspace)
+    registry = build_registry(workspace, memory)
+
+    # Project rules (AGENTS.md) are binding: inject them into the system prompt.
+    rules_text, rules_source = load_rules(workspace)
+    system_prompt = build_system_prompt(config.SYSTEM_PROMPT, rules_text, rules_source)
+    notes = memory.load_notes()
+    if notes:
+        system_prompt += "\n\nREMEMBERED NOTES:\n" + "\n".join(f"- {n}" for n in notes)
+    policy = PermissionPolicy(
+        ask=ask_permission,
+        auto_approve=config.AUTO_APPROVE,
+        on_event=lambda msg: print(f"  {msg}"),
+    )
+    core = AgentCore(
+        client=client,
+        model=model,
+        registry=registry,
+        system_prompt=system_prompt,
+        max_steps=config.MAX_STEPS,
+        max_context_chars=config.MAX_CONTEXT_CHARS,
+        on_event=lambda msg: print(f"  {msg}"),
+        policy=policy,
+    )
+
+    # Build the knowledge base and skills system.
+    # Global knowledge lives alongside the installed package.
+    global_root = str(Path(__file__).resolve().parent)
+    knowledge = KnowledgeBase(project_root=workspace.root, global_root=global_root)
+    skills = Skills(root=workspace.root)
+    # Build the agent router that dispatches to specialized agents.
+    router = AgentRouter(core, skills, knowledge, workspace)
+    # Detect local hardware for image/video capability assessment.
+    hw = detect_hardware()
+    hw_summary = summarize_hardware(hw)
+
+    print(BANNER)
+    print(f"Project: {workspace.name}  ({workspace.root})")
+    stack = workspace.detect_stack()
+    if stack:
+        print(f"Detected: {', '.join(stack)}")
+    if rules_source:
+        print(f"Rules  : {rules_source} loaded")
+    if is_git_repo(workspace):
+        current = branch(workspace) or "?"
+        print(f"Git    : {current} ({len(changed_files(workspace))} changed file(s))")
+    print(f"Ollama : {config.OLLAMA_HOST}")
+    print(f"Model  : {model}")
+    print(f"Tools  : {len(registry)} available (/tools to list)")
+    print(f"Agents : {len(router)} registered (/agents to list)")
+    print(f"Skills : {len(skills.all_skills())} loaded (/skills to list)")
+    print(f"Knowledge: {len(knowledge.entries())} entries (/knowledge to search)")
+    print(f"Hardware: {hw_summary}")
+    if not hw.vram_available_gb or hw.vram_available_gb < 4:
+        print("Note: Local image/video generation requires >= 4 GB available VRAM or external provider.")
+    if config.AUTO_APPROVE:
+        print("WARNING: auto-approve is ON — file writes will NOT be confirmed.")
+    print("Type /help for commands, /exit to quit.")
+
+    if len(sys.argv) > 1:
+        prompt = " ".join(sys.argv[1:])
+        return run_once(core, prompt)
+
+    run_chat(core, registry, workspace, memory, router=router, skills=skills, knowledge=knowledge, hardware=hw)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/install.ps1

@@ -0,0 +1,28 @@
+# Adds this project's bin folder to your USER PATH so you can run `eljay`.
+# Run it yourself from PowerShell:   .\install.ps1
+# It only changes your user environment; it does not touch system settings.
+
+$bin = Join-Path $PSScriptRoot 'bin'
+
+if (-not (Test-Path $bin)) {
+    Write-Host "bin folder not found: $bin" -ForegroundColor Red
+    exit 1
+}
+
+$current = [Environment]::GetEnvironmentVariable('Path', 'User')
+if ($null -eq $current) { $current = '' }
+
+if (($current -split ';') -contains $bin) {
+    Write-Host "Already on your user PATH: $bin" -ForegroundColor Yellow
+} else {
+    $newPath = if ($current.Trim() -eq '') { $bin } else { "$current;$bin" }
+    [Environment]::SetEnvironmentVariable('Path', $newPath, 'User')
+    Write-Host "Added to your user PATH: $bin" -ForegroundColor Green
+}
+
+Write-Host ""
+Write-Host "Restart your terminal, then run the agent from any project folder:"
+Write-Host "    cd C:\Projects\your-project"
+Write-Host "    eljay"
+Write-Host ""
+Write-Host "The old command `myagent` also still works as an alias."

package/knowledge/reference/diffusers.md

@@ -0,0 +1,32 @@
+# Diffusers (Hugging Face)
+
+Diffusers is the Hugging Face library for diffusion models (Stable Diffusion, etc.).
+
+## Installation
+
+```powershell
+pip install diffusers[torch] transformers accelerate
+```
+
+## Key Models
+
+- `stabilityai/sdxl` — SDXL (requires 8+ GB VRAM)
+- `runwayml/stable-diffusion-v1-5` — SD 1.5 (requires 4+ GB VRAM)
+- `stabilityai/stable-diffusion-2-1` — SD 2.1
+
+## Usage
+
+```python
+from diffusers import StableDiffusionPipeline
+pipe = StableDiffusionPipeline.from_pretrained("runwayml/stable-diffusion-v1-5")
+image = pipe("a futuristic Filipino city, cyberpunk style").images[0]
+image.save("output.png")
+```
+
+## Notes
+
+- CPU-only generation is possible with `torch_dtype=torch.float32` but very slow.
+- Use `pipe.enable_attention_slicing()` to reduce VRAM.
+- Models download on first use (~2-7 GB each).
+
+Source: https://github.com/huggingface/diffusers

package/knowledge/reference/video-providers.md

@@ -0,0 +1,21 @@
+# Video Generation Providers — Status Matrix
+
+Video generation is extremely resource-intensive (VRAM + compute).
+
+| Provider | Type | Free? | VRAM | Notes |
+|---|---|---|---|---|
+| ComfyUI + AnimateDiff | Local | Free | 6+ GB | Best local option |
+| diffusers + AnimateDiff | Local | Free | 6+ GB | Requires AnimateDiff |
+| --- | --- | --- | --- | --- |
+| RunwayML | API | Paid | — | High quality |
+| Pika Labs | API | Free tier | — | Limited generations/day |
+| Stable Video Diffusion | Local | Free | 10+ GB | Very slow on CPU |
+
+## Hardware Requirements
+
+- **Minimum for local**: 6 GB VRAM (SD 1.5), 8 GB VRAM (SDXL)
+- **Recommended**: 12+ GB VRAM for smooth generation
+- **CPU-only**: technically possible but 100–1000x slower; not practical
+
+If this machine has no discrete GPU with 6+ GB VRAM, video generation is not
+practical locally. Cloud API services are the alternative for this task.

package/knowledge/setup/comfyui.md

@@ -0,0 +1,35 @@
+# ComfyUI Setup
+
+ComfyUI is a free, open-source, node-based UI for Stable Diffusion. It runs locally
+and supports both GPU and CPU generation.
+
+## Installation (Windows)
+
+```powershell
+git clone https://github.com/comfyanonymous/ComfyUI.git
+cd ComfyUI
+pip install -r requirements.txt
+python main.py
+```
+
+## Configuration
+
+- Set `COMFYUI_DIR` environment variable to your ComfyUI folder.
+- ElJay AI will auto-detect ComfyUI at `%USERPROFILE%\ComfyUI`.
+- The UI runs at http://127.0.0.1:8188.
+
+## Usage with ElJay
+
+```text
+eljay> generate_image prompt="a lone cowboy in a ruined Western town"
+```
+
+ComfyUI will queue the generation. Check the UI for results.
+
+## Notes
+
+- CPU generation is possible but 10–50x slower than GPU.
+- VRAM requirements: 4+ GB for SD 1.5, 8+ GB for SDXL.
+- Models download to `ComfyUI/models/checkpoints/`.
+
+Source: https://github.com/comfyanonymous/ComfyUI

package/knowledge/setup/image-providers.md

@@ -0,0 +1,16 @@
+# Image Generation Providers — Status Matrix
+
+| Provider | Type | Cost | API Key? | Notes |
+|---|---|---|---|---|
+| ComfyUI | Local | Free | No | Best quality; Windows-friendly; CPU works |
+| diffusers + torch | Local | Free | No | Flexible; CPU possible but slow |
+| Ollama vision | Local | Free | No | Can edit images, not generate from text |
+| --- | --- | --- | --- | --- |
+| Hugging Face Inference | API | Free tier | Yes (HF token) | Limited; rate-limited |
+| Stability AI | API | Paid | Yes | Reliable; ~$0.002/image |
+| Replicate | API | Paid | Yes | Many models; pay per use |
+
+## Recommendation
+
+For local-only setups without a GPU, ComfyUI on CPU is the most practical option.
+No free public API can generate images reliably without rate-limiting or API keys.

package/knowledge/test-category/test-entry.md

@@ -0,0 +1,5 @@
+# a test entry about Python
+
+<!-- 2026-10-01 -->
+
+Python is a programming language

package/myagent.py

@@ -0,0 +1,30 @@
+"""Compatibility alias for ElJay AI.
+
+This file is kept for backwards compatibility. It simply delegates to
+``eljay.py`` so existing workflows (`python myagent.py`, the `myagent`
+launcher) continue to work while the canonical entry point is ``eljay``.
+
+Usage:
+    python myagent.py                 -> same as `python eljay.py`
+    python myagent.py "your prompt"   -> same as `python eljay.py "..."`
+
+.. deprecated:: 1.1.0
+    Use `eljay` / `python eljay.py` instead.
+"""
+
+import sys
+from pathlib import Path
+
+# Ensure the project root (parent of this file) is on sys.path so the
+# `eljay` module can be imported regardless of the launch directory.
+_PROJECT_ROOT = Path(__file__).resolve().parent
+if str(_PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(_PROJECT_ROOT))
+
+from eljay import main  # noqa: E402
+
+# Preserve the old module-level name for any code that imports it.
+from eljay import resolve_model, build_registry  # noqa: E402,F401
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "eljay-ai",
+  "version": "1.1.0",
+  "description": "ElJay AI — a free, local, terminal-based universal AI assistant with Ollama LLM, web research, image & video generation, skills, knowledge base, and project-local memory. Standard library Python only.",
+  "keywords": [
+    "ai",
+    "agent",
+    "coding-agent",
+    "ollama",
+    "local-ai",
+    "cli",
+    "terminal",
+    "code-generation",
+    "universal-ai-assistant",
+    "image-generation",
+    "web-research",
+    "skills",
+    "knowledge-base"
+  ],
+  "author": "ElJay AI",
+  "license": "MIT",
+  "bin": {
+    "eljay": "eljay.js",
+    "eljay-ai": "eljay.js"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "python": ">=3.12.0"
+  },
+  "preferGlobal": true,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eljay-ai/eljay-ai.git"
+  },
+  "homepage": "https://github.com/eljay-ai/eljay-ai#readme",
+  "funding": {
+    "type": "individual",
+    "url": "https://github.com/sponsors/eljay-ai"
+  }
+}

package/skills/coding/code-review.md

@@ -0,0 +1,3 @@
+# Code Review
+
+Check for: correctness, edge cases, security issues, readability, and adherence to existing project conventions.

package/skills/coding/fix-attempt-protocol.md

@@ -0,0 +1,9 @@
+# Fix Attempt Protocol
+
+1. Inspect the project structure.
+2. Understand the codebase and locate the relevant code.
+3. Explain the problem clearly.
+4. Propose a fix.
+5. Ask for permission before risky changes.
+6. Make the edit.
+7. Verify the actual tool result — never claim success without evidence.

package/skills/debugging/root-cause-analysis.md

@@ -0,0 +1,9 @@
+# Root Cause Analysis
+
+1. Reproduce the error with the actual command/test.
+2. Read the relevant source files.
+3. Trace data flow from input to failure.
+4. Form a hypothesis about the root cause.
+5. Test the hypothesis with a minimal change or log.
+6. Fix the root cause, not the symptom.
+7. Verify the fix resolves the error and does not introduce new ones.

package/skills/general/communication.md

@@ -0,0 +1,7 @@
+# Communication Guidelines
+
+- Be concise and accurate. Never fabricate facts.
+- If unsure, say so and suggest how to find out.
+- Match the user's technical level; explain concepts clearly.
+- Use examples when helpful, but keep answers focused.
+- Structure longer answers with headings and lists for readability.

package/skills/laravel/authentication.md

@@ -0,0 +1,15 @@
+# Laravel Authentication
+
+Laravel provides authentication out of the box via Breeze, Jetstream, or Fortify.
+
+Key concepts:
+- `php artisan make:auth` (legacy) / `composer require laravel/breeze`
+- Guards define how users are authenticated for each request.
+- Providers define how users are retrieved from the database.
+- Middleware: `auth`, `guest`, `verified`.
+- Sanctum for API tokens; Passport for OAuth2.
+
+Common issues:
+- Session not persisting → check SESSION_DRIVER and SESSION_DOMAIN.
+- Token mismatch → ensure CSRF token is included in forms.
+- Email verification → run `php artisan migrate` and use Notifiable trait.

package/skills/mysql/performance.md

@@ -0,0 +1,9 @@
+# MySQL Performance
+
+- Index columns used in WHERE, JOIN, ORDER BY clauses.
+- Use EXPLAIN to understand query plans.
+- Avoid SELECT *; fetch only needed columns.
+- Prefer InnoDB over MyISAM for transaction support.
+- Set innodb_buffer_pool_size to ~70% of available RAM.
+- Use connection pooling for high-throughput applications.
+- Normalize to 3NF, denormalize for read-heavy reporting where needed.

package/skills/php/standards.md

@@ -0,0 +1,8 @@
+# PHP Coding Standards
+
+- Use PSR-12 formatting.
+- Type hint parameters and return types whenever possible.
+- Use strict comparisons (===, !==).
+- Prefer null coalescing (??) over isset chains.
+- Use named arguments in PHP 8+ for clarity with many parameters.
+- Enable error reporting in development: error_reporting(E_ALL).

package/skills/react/component-best-practices.md

@@ -0,0 +1,8 @@
+# React Component Best Practices
+
+- Keep components small and focused (single responsibility).
+- Use props for configuration, state for mutable data.
+- Extract custom hooks for reusable logic.
+- Avoid side effects in render; use useEffect.
+- Memoize expensive computations with useMemo/useCallback.
+- Test components with the testing-library approach: render, query, assert.

package/skills/research/source-tracking.md

@@ -0,0 +1,7 @@
+# Source Tracking
+
+- Always cite sources: title, URL, publication/author, date accessed.
+- Distinguish: direct quotes, paraphrased information, and your own reasoning.
+- Never fabricate a citation or pretend a source was consulted.
+- Prefer official documentation, then primary sources, then reputable secondary sources.
+- Summarize in your own words; include key quotes sparingly and with attribution.

package/skills/security/input-validation.md

@@ -0,0 +1,9 @@
+# Input Validation and Sanitization
+
+- Validate all input on the server side — never trust the client.
+- Use allow-lists (whitelists) over block-lists (blacklists).
+- Sanitize before storing, escape on output.
+- For SQL: use parameterized queries/prepared statements.
+- For HTML: escape output with htmlspecialchars() or a templating engine.
+- For shells: avoid user input in commands; use argument arrays.
+- Set strict limits on input length and character sets.

package/skills/testing/pytest-best-practices.md

@@ -0,0 +1,7 @@
+# Pytest Best Practices
+
+- Name test files `test_*.py`, test classes `*Tests`, test functions `test_*`.
+- One assertion per test; use parametrize for variations.
+- Mock network/external services; assert on the real contract.
+- Run tests from the project root: `python tests/run_all.py`.
+- Never write a test that depends on a specific LLM response.

package/tests/run_all.py

@@ -0,0 +1,34 @@
+"""Run every test module under tests/.
+
+    python tests/run_all.py
+"""
+
+import glob
+import os
+import subprocess
+import sys
+
+
+def main() -> int:
+    here = os.path.dirname(os.path.abspath(__file__))
+    modules = sorted(glob.glob(os.path.join(here, "test_*.py")))
+    if not modules:
+        print("No test modules found.")
+        return 1
+
+    failures = 0
+    for path in modules:
+        print(f"\n=== {os.path.basename(path)} ===")
+        result = subprocess.call([sys.executable, path])
+        failures += result != 0
+
+    print()
+    if failures:
+        print(f"{failures} test module(s) FAILED.")
+        return 1
+    print(f"All {len(modules)} test modules passed.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())