golden-agent 0.1.0__tar.gz

golden_agent-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.env
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.vscode/

golden_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yashneil Gajjala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

golden_agent-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.5
+Name: golden-agent
+Version: 0.1.0
+Summary: Your local AI agent. Runs on basically any hardware — auto-setup, GPU-accelerated, zero cloud, zero API keys.
+Author-email: Yashneil Gajjala <yashneil75@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,cli,coding-agent,gguf,llama-cpp,llm,local,local-llm,offline,tools,vulkan
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Requires-Dist: ddgs>=9.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: markrender>=1.0.7
+Requires-Dist: prompt-toolkit>=3.0.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Golden Agent
+
+**Your local AI agent. No cloud. No API keys. No excuses.**
+
+A terminal coding agent that runs entirely on your machine — auto-installs its own
+GPU-accelerated inference stack, auto-downloads models, and gets to work on basically
+any post 2000 hardware.
+---
+
+## Why Golden Agent?
+
+Every AI coding assistant wants your code uploaded to someone else's server.
+Golden Agent flips that: the model, the tools, and your data never leave your machine.
+
+- **100% local** — inference happens on-device via llama.cpp. Nothing is sent anywhere (except when *you* ask it to search or fetch the web).
+- **Zero-config setup** — one `pip install`, one command. Golden Agent detects your GPU and downloads the matching prebuilt llama.cpp backend automatically (Vulkan on Windows/Linux, Metal on macOS, CUDA where available, CPU otherwise), then pulls the model weights from Hugging Face with resumable, retry-hardened downloads.
+- **Runs on basically any hardware** — Vulkan means one code path for NVIDIA, AMD, and Intel GPUs. Full offload, flash attention, and Q5_0 KV-cache quantization squeeze maximum performance out of modest VRAM. Small models start at ~1.5 GB — a laptop iGPU can run it.
+- **A real agent, not a chatbot** — reads and edits files, runs shell commands, searches the web, fetches pages, and loops on results until the job is done. Writes outside your project ask first.
+- **Models for everyone** — three sizes from 1.5 GB to 8.2 GB, switchable with a numbered picker on startup.
+
+## Quickstart
+
+```bash
+pip install golden-agent
+golden-agent setup
+golden-agent
+```
+
+That's it. First launch:
+1. Golden Agent sets up the llama.cpp wheel for your platform.
+1. Pick a model
+3. The model downloads on first run (~1.5–9 GB, resumable if interrupted).
+4. You get a prompt: `❯` — start asking it to do things.
+
+```text
+❯ fix the failing test in tests/test_agent.py
+❯ search for how uv handles lockfiles and summarize
+❯ write a script that renames all photos by EXIF date
+```
+
+## Models
+
+| Key | Model | Size | Context | Good for |
+|---|---|---|---|---|
+| `tiny` | [LFM2.5-2.6B](https://huggingface.co/LiquidAI/LFM2.5-2.6B-GGUF) | ~1.5 GB | 128K | Low-end hardware, laptops, iGPUs |
+| `lite` *(default)* | [Ornith-1.5-9B](https://huggingface.co/AtomicChat/Ornith-1.5-9B-GGUF) | ~5.2 GB | 153K | Best balance of speed and capability |
+| `pro` | [Qwen3.8-27B](https://huggingface.co/sdkyuan/qwen3.8-27b-qat-q2_0-gguf) | ~8.2 GB | 153K | Heavy reasoning when you can afford it |
+
+## Built-in tools
+
+Golden Agent ships with six tools the model uses autonomously:
+
+| Tool | What it does |
+|---|---|
+| `read_file` | Reads files with automatic paging for large ones |
+| `write_file` | Creates/overwrites files |
+| `edit_file` | Exact-match string replacement (with `replace_all`) |
+| `bash` | Runs real shell commands — actual bash even on Windows |
+| `web_search` | DuckDuckGo search |
+| `web_fetch` | Fetches a URL and extracts readable text |
+
+**Guardrails:** file writes outside the directory you launched from trigger an
+interactive permission prompt (`once` / `always this session` / `deny`). Tool output
+is capped so runaway commands can't flood the context.
+
+## What you'll see
+
+- **Live streaming markdown** as the model writes.
+- **Visible reasoning** — `<think>` blocks stream inline, dimmed, so you can watch it think.
+- **Tool activity panels** — file diffs and command output render with syntax highlighting; reads and searches show as quiet status lines.
+- **Automatic context compaction** — past 140K tokens, older turns are summarized by the model itself so long sessions keep going.
+
+## Slash commands
+
+```
+/tools            list available tools
+/clear            wipe conversation history
+/help             show help
+/exit             quit
+```
+
+## Requirements
+
+- Python 3.10+
+- A GPU (NVIDIA, AMD, Intel) — or it still works on CPU, just slower.
+- Internet once, for the initial setup + model download. After that: fully offline.
+
+Golden Agent downloads a prebuilt llama.cpp binary for your detected backend, so no
+compilation is required. If you want to build a custom backend yourself, the
+[Vulkan SDK](https://vulkan.lunarg.com/sdk/home) is only needed for that manual path.
+
+## Under the hood
+
+- **Inference:** the prebuilt `llama-server` with full GPU offload (`-ngl 99`), flash attention, and Q5_0-quantized KV cache.
+- **Downloads:** direct-from-HuggingFace GGUF fetching with HTTP range resume, byte-exact validation, and exponential-backoff retries.
+- **Tool calling:** hand-rolled parsers for both Qwen-style XML calls and LFM2 pythonic call syntax — robust to streaming chunk boundaries, unclosed tags, and parallel calls.
+- **Model cache:** `%LOCALAPPDATA%\golden-agent\models` (Windows), `~/Library/Caches/golden-agent/models` (macOS), `$XDG_CACHE_HOME/golden-agent/models` (Linux).
+
+### Debugging
+
+Set `GOLDEN_AGENT_RAW_LOG` to a file path to capture every raw model response — invaluable
+when a tool call goes sideways:
+
+```bash
+GOLDEN_AGENT_RAW_LOG=./raw.log golden-agent
+```
+
+## Development
+
+```bash
+git clone <repo> && cd golden-agent
+pip install -e .[dev]
+pytest
+ruff check src tests
+```
+
+Run without installing:
+
+```bash
+pip install -e .
+python -m golden_agent
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

golden_agent-0.1.0/README.md

@@ -0,0 +1,126 @@
+# Golden Agent
+
+**Your local AI agent. No cloud. No API keys. No excuses.**
+
+A terminal coding agent that runs entirely on your machine — auto-installs its own
+GPU-accelerated inference stack, auto-downloads models, and gets to work on basically
+any post 2000 hardware.
+---
+
+## Why Golden Agent?
+
+Every AI coding assistant wants your code uploaded to someone else's server.
+Golden Agent flips that: the model, the tools, and your data never leave your machine.
+
+- **100% local** — inference happens on-device via llama.cpp. Nothing is sent anywhere (except when *you* ask it to search or fetch the web).
+- **Zero-config setup** — one `pip install`, one command. Golden Agent detects your GPU and downloads the matching prebuilt llama.cpp backend automatically (Vulkan on Windows/Linux, Metal on macOS, CUDA where available, CPU otherwise), then pulls the model weights from Hugging Face with resumable, retry-hardened downloads.
+- **Runs on basically any hardware** — Vulkan means one code path for NVIDIA, AMD, and Intel GPUs. Full offload, flash attention, and Q5_0 KV-cache quantization squeeze maximum performance out of modest VRAM. Small models start at ~1.5 GB — a laptop iGPU can run it.
+- **A real agent, not a chatbot** — reads and edits files, runs shell commands, searches the web, fetches pages, and loops on results until the job is done. Writes outside your project ask first.
+- **Models for everyone** — three sizes from 1.5 GB to 8.2 GB, switchable with a numbered picker on startup.
+
+## Quickstart
+
+```bash
+pip install golden-agent
+golden-agent setup
+golden-agent
+```
+
+That's it. First launch:
+1. Golden Agent sets up the llama.cpp wheel for your platform.
+1. Pick a model
+3. The model downloads on first run (~1.5–9 GB, resumable if interrupted).
+4. You get a prompt: `❯` — start asking it to do things.
+
+```text
+❯ fix the failing test in tests/test_agent.py
+❯ search for how uv handles lockfiles and summarize
+❯ write a script that renames all photos by EXIF date
+```
+
+## Models
+
+| Key | Model | Size | Context | Good for |
+|---|---|---|---|---|
+| `tiny` | [LFM2.5-2.6B](https://huggingface.co/LiquidAI/LFM2.5-2.6B-GGUF) | ~1.5 GB | 128K | Low-end hardware, laptops, iGPUs |
+| `lite` *(default)* | [Ornith-1.5-9B](https://huggingface.co/AtomicChat/Ornith-1.5-9B-GGUF) | ~5.2 GB | 153K | Best balance of speed and capability |
+| `pro` | [Qwen3.8-27B](https://huggingface.co/sdkyuan/qwen3.8-27b-qat-q2_0-gguf) | ~8.2 GB | 153K | Heavy reasoning when you can afford it |
+
+## Built-in tools
+
+Golden Agent ships with six tools the model uses autonomously:
+
+| Tool | What it does |
+|---|---|
+| `read_file` | Reads files with automatic paging for large ones |
+| `write_file` | Creates/overwrites files |
+| `edit_file` | Exact-match string replacement (with `replace_all`) |
+| `bash` | Runs real shell commands — actual bash even on Windows |
+| `web_search` | DuckDuckGo search |
+| `web_fetch` | Fetches a URL and extracts readable text |
+
+**Guardrails:** file writes outside the directory you launched from trigger an
+interactive permission prompt (`once` / `always this session` / `deny`). Tool output
+is capped so runaway commands can't flood the context.
+
+## What you'll see
+
+- **Live streaming markdown** as the model writes.
+- **Visible reasoning** — `<think>` blocks stream inline, dimmed, so you can watch it think.
+- **Tool activity panels** — file diffs and command output render with syntax highlighting; reads and searches show as quiet status lines.
+- **Automatic context compaction** — past 140K tokens, older turns are summarized by the model itself so long sessions keep going.
+
+## Slash commands
+
+```
+/tools            list available tools
+/clear            wipe conversation history
+/help             show help
+/exit             quit
+```
+
+## Requirements
+
+- Python 3.10+
+- A GPU (NVIDIA, AMD, Intel) — or it still works on CPU, just slower.
+- Internet once, for the initial setup + model download. After that: fully offline.
+
+Golden Agent downloads a prebuilt llama.cpp binary for your detected backend, so no
+compilation is required. If you want to build a custom backend yourself, the
+[Vulkan SDK](https://vulkan.lunarg.com/sdk/home) is only needed for that manual path.
+
+## Under the hood
+
+- **Inference:** the prebuilt `llama-server` with full GPU offload (`-ngl 99`), flash attention, and Q5_0-quantized KV cache.
+- **Downloads:** direct-from-HuggingFace GGUF fetching with HTTP range resume, byte-exact validation, and exponential-backoff retries.
+- **Tool calling:** hand-rolled parsers for both Qwen-style XML calls and LFM2 pythonic call syntax — robust to streaming chunk boundaries, unclosed tags, and parallel calls.
+- **Model cache:** `%LOCALAPPDATA%\golden-agent\models` (Windows), `~/Library/Caches/golden-agent/models` (macOS), `$XDG_CACHE_HOME/golden-agent/models` (Linux).
+
+### Debugging
+
+Set `GOLDEN_AGENT_RAW_LOG` to a file path to capture every raw model response — invaluable
+when a tool call goes sideways:
+
+```bash
+GOLDEN_AGENT_RAW_LOG=./raw.log golden-agent
+```
+
+## Development
+
+```bash
+git clone <repo> && cd golden-agent
+pip install -e .[dev]
+pytest
+ruff check src tests
+```
+
+Run without installing:
+
+```bash
+pip install -e .
+python -m golden_agent
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

golden_agent-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "golden-agent"
+version = "0.1.0"
+description = "Your local AI agent. Runs on basically any hardware — auto-setup, GPU-accelerated, zero cloud, zero API keys."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Yashneil Gajjala", email = "yashneil75@gmail.com" }]
+keywords = [
+    "agent",
+    "cli",
+    "coding-agent",
+    "gguf",
+    "llama-cpp",
+    "llm",
+    "local",
+    "local-llm",
+    "offline",
+    "tools",
+    "vulkan",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development",
+]
+dependencies = [
+    "httpx>=0.27.0",
+    "rich>=13.0.0",
+    "markrender>=1.0.7",
+    "ddgs>=9.0.0",
+    "prompt_toolkit>=3.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "ruff>=0.4.0",
+]
+
+[project.scripts]
+golden-agent = "golden_agent.cli:repl"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/golden_agent"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/golden_agent/config.py" = ["E501"]
+"src/golden_agent/cli.py" = ["E501"]
+"src/golden_agent/system_prompt.py" = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

golden_agent-0.1.0/src/golden_agent/__main__.py

@@ -0,0 +1,3 @@
+from golden_agent.cli import repl
+
+repl()