{"id":28760817,"url":"https://github.com/satunix/agent-1","last_synced_at":"2025-06-17T06:10:07.858Z","repository":{"id":296339346,"uuid":"991988697","full_name":"SATUNIX/Agent-1","owner":"SATUNIX","description":"An offline‑first agent network that combines two complementary pipelines:","archived":false,"fork":false,"pushed_at":"2025-05-30T05:16:44.000Z","size":15,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-05-30T06:46:48.571Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SATUNIX.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":"citations.py","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-28T12:57:37.000Z","updated_at":"2025-05-30T05:19:32.000Z","dependencies_parsed_at":"2025-05-30T06:46:56.756Z","dependency_job_id":"6a32e7d6-b9d0-440b-8003-5a45220641e3","html_url":"https://github.com/SATUNIX/Agent-1","commit_stats":null,"previous_names":["satunix/agent-1"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/SATUNIX/Agent-1","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SATUNIX%2FAgent-1","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SATUNIX%2FAgent-1/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SATUNIX%2FAgent-1/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SATUNIX%2FAgent-1/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SATUNIX","download_url":"https://codeload.github.com/SATUNIX/Agent-1/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SATUNIX%2FAgent-1/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260302004,"owners_count":22988726,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-17T06:10:07.388Z","updated_at":"2025-06-17T06:10:07.835Z","avatar_url":"https://github.com/SATUNIX.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Network System (Build 1) (Experimental - Untested)\r\n\r\nAn **offline‑first agent network** that combines two complementary pipelines:\r\n\r\n| Pipeline    | Entry‑point                   | Purpose                                                                                                                                                     |\r\n| ----------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |\r\n| **Classic** | `python run.py \"\u003cgoal\u003e\"`      | Planner → Writer → Open‑Interpreter DevAgent. Great for documentation‑heavy tasks that also need live code edits with sandboxed execution.                  |\r\n| **Modern**  | `python run_loop.py \"\u003cgoal\u003e\"` | ManagerAgent → LLMDevAgent. Demonstrates shared‐memory coordination and token‑aware trimming when you want pure LLM reasoning with optional code execution. |\r\n\r\n\u003e **One machine – one inference at a time.**  Both pipelines enforce sequential LLM calls so a single Ollama instance (CPU or GPU) is never double‑booked.\r\n\r\n---\r\n\r\n## 1  System Diagram\r\n\r\n```mermaid\r\ngraph TD\r\n    subgraph Classic\r\n        U(User)-- goal --\u003eP(PlannerAgent)\r\n        P--\u003eW(WriterAgent)\r\n        P--\u003eD1(Open‑Interpreter DevAgent)\r\n        W--\u003eDocs\r\n        D1--\u003eGit\r\n    end\r\n\r\n    subgraph Modern\r\n        U-.-\u003eM(ManagerAgent)\r\n        M--\u003eD2(LLMDevAgent)\r\n        D2--\u003eM\r\n        D2--\u003eGit2\r\n    end\r\n\r\n    Memory((Shared Memory))\r\n    P-- read/write --\u003eMemory\r\n    W-- read/write --\u003eMemory\r\n    M-- read/write --\u003eMemory\r\n    D2-- read/write --\u003eMemory\r\n```\r\n\r\n---\r\n\r\n## 2  Hardware Requirements\r\n\r\n| Component | Minimum                    | Recommended                                                                   |\r\n| --------- | -------------------------- | ----------------------------------------------------------------------------- |\r\n| **CPU**   | Any 4‑core x64             | 6+ cores for parallel build/test during code execution                        |\r\n| **RAM**   | 8 GB                       | 16 GB+ (DeepSeek‑R1 7B quantised uses \\~6 GB)                                 |\r\n| **GPU**   | *(Optional)* Integrated    | NVIDIA RTX 30‑series or Intel ARC with ≥8 GB vRAM for faster Ollama inference |\r\n| **Disk**  | 5 GB free (models)         | 15 GB+ if you pull multiple models (DeepSeek‑Coder, CodeLlama, etc.)          |\r\n| **OS**    | Windows 10 64‑bit or later | Windows 11 22H2 with WSL 2 for Linux‑style tooling                            |\r\n\r\n\u003e *The system is equally happy on Linux/macOS, but the scripts assume a Windows host path for temporary files.*\r\n\r\n---\r\n\r\n## 3  Software Stack\r\n\r\n* **Python ≥ 3.10**  (`python --version`)\r\n* **Ollama ≥ 0.1.23** (local LLM server)\r\n* **Git for Windows** ( command‑line `git` )\r\n* **Visual Studio Build Tools** *(only if Open‑Interpreter needs C++ extensions)*\r\n* **Python packages** – install via `pip install -r requirements.txt`\r\n\r\n  * `open‑interpreter`, `duckduckgo‑search`, `beautifulsoup4`, `lxml`, `requests`, `pytest`, *optional* `tiktoken`, `ollama‑python`.\r\n\r\n### 3.1  Pulling Models\r\n\r\n```powershell\r\n# DeepSeek‑R1 7B for reasoning / planning\r\nollama pull deepseek-r1:7b\r\n# DeepSeek‑Coder for code‑centric DevAgent\r\nollama pull deepseek-coder\r\n```\r\n\r\n\u003e Quantised (`q4_K_M`) models work fine; they reduce VRAM/RAM usage \\~40%.\r\n\r\n---\r\n\r\n## 4  Setup\r\n\r\n```powershell\r\npython -m venv .venv\r\n.\\.venv\\Scripts\\Activate.ps1\r\npip install -r requirements.txt\r\n\r\n# optional env‑vars ( PowerShell )\r\n$env:OLLAMA_URL = \"http://localhost:11434\"\r\n$env:DEV_MODEL   = \"deepseek-coder\"\r\n$env:AGENT_MODEL = \"deepseek-r1:7b\"\r\n```\r\nCreate an environment file (not provided in this repository) \r\nTemplate below. \r\n\r\n```\r\nOLLAMA_API=http://localhost:11434/api/generate\r\n# Models\r\nPLANNER_MODEL=deepseek-r1:7b\r\nWRITER_MODEL=deepseek-r1:7b\r\nDEV_MODEL=deepseek-coder\r\nTEST_COMMAND=pytest         \r\n\r\n```\r\n\r\nCreate a fresh Git repo so snapshots work:\r\n\r\n```powershell\r\ngit init\r\n```\r\n\r\n---\r\n\r\n## 5  Usage\r\n\r\n### 5.1  Documentation‑first (Classic) Pipeline\r\n\r\n```powershell\r\npython run.py \"Document and implement a CLI to compute prime numbers\"\r\n```\r\n\r\n**What happens**\r\n\r\n1. Planner splits request into `[Doc]` and `[Code]` tasks.\r\n2. Writer drafts Markdown docs; missing facts trigger DuckDuckGo research.\r\n3. DevAgent (Open‑Interpreter) edits files and runs tests; commits via Git.\r\n\r\nAll docs land in `/docs/*.md`.  Commits are timestamped auto‑messages.\r\n\r\n### 5.2  Manager + LLMDev Pipeline\r\n\r\n```powershell\r\npython run_loop.py \"Build a simple calculator that adds two numbers\"\r\n```\r\n\r\n1. ManagerAgent creates a plan (CoT inside `\u003cthink\u003e` tags).\r\n2. LLMDevAgent writes \u0026 executes code; result inserted back into memory.\r\n3. Manager reviews and outputs a user‑friendly conclusion.\r\n\r\nRun‐loop demonstrates **shared `Memory`** trimming to stay under 1500 tokens.\r\n\r\n---\r\n\r\n## 6  Testing\r\n\r\n* **Unit tests**: place `*_test.py` or `test_*.py` files; they’re auto‑run by `pytest` inside the DevAgent fallback.\r\n* **Manual**: inspect `.git` log to ensure only passing states are committed.\r\n* **Timing**: each LLM call has a 300 s timeout; if a model is slow on first load, subsequent calls are cached in RAM.\r\n\r\n---\r\n\r\n## 7  Troubleshooting\r\n\r\n| Symptom                                         | Fix                                                                       |\r\n| ----------------------------------------------- | ------------------------------------------------------------------------- |\r\n| `requests.exceptions.ConnectionError` to Ollama | Is Ollama running? `ollama serve`                                         |\r\n| JSON key `'output'` missing                     | Upgrade Ollama ≥ 0.1.23 **or** edit `agents.py` fallback to `'response'`. |\r\n| GPU OOM                                         | Use quantised model (`:q4_K_M`) or switch to CPU (`OLLAMA_NUM_GPU=0`).    |\r\n| Endless context growth                          | `Memory.trim()` thresholds can be lowered (e.g. `max_tokens=1000`).       |\r\n| DuckDuckGo blocked                              | Set `DDG_OFFLINE=1` and stub `search_tool.ddg_search`.                    |\r\n\r\n---\r\n\r\n## 8  Extending the System\r\n\r\n* **Add more specialised agents** – e.g. a TesterAgent that only writes `pytest` suites, then let DevAgent implement fixes.\r\n* **Vector store memory** – plug a lightweight Chroma DB; store full docs, keep only semantic summaries in prompt.\r\n* **Async scheduler** – wrap Ollama calls in an `asyncio.Lock` to allow background I/O while respecting single‑GPU inference.\r\n* **GUI** – build a simple Tk or Electron front‑end calling the same CLI scripts.\r\n\r\nPull requests welcome!  Enjoy your local multi‑agent workstation 🚀\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsatunix%2Fagent-1","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsatunix%2Fagent-1","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsatunix%2Fagent-1/lists"}