Add README instructions and CI

Author: nschlaepfer

.github/workflows/lint.yml

@@ -0,0 +1,14 @@
+name: Unit-&-Lint
+on:
+  push:
+    paths: ["agent/**", "pyproject.toml"]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - run: pip install -e .[dev]
+      - run: python -m pytest -q

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "externals/llama.cpp"]
+path = externals/llama.cpp
+url = https://github.com/ggerganov/llama.cpp

README.md

@@ -765,3 +765,16 @@ If you use this code, please cite:
 ## License
 
 MIT License. See [LICENSE](LICENSE) for details.
+
+## 🔥 Local Qwen 3 Agent (Apple Silicon)
+
+> New in `qwen3-agent` branch
+
+1. `brew install cmake rust`
+2. `git submodule update --init`
+3. `bash scripts/build_llama_metal.sh`
+4. `pip install -e .`
+5. Download **Qwen3-14B-Q4_K_M.gguf** ➜ `~/models`
+6. `bash scripts/run_agent.sh`
+
+The `run_agent.sh` script exports the config path and launches `python -m agent.main`. Users on Intel Macs can unset `LLAMA_METAL` to force CPU inference.

agent/__init__.py

@@ -0,0 +1,21 @@
+[model]
+# path to the local GGUF model
+gguf_path = "~/models/Qwen3-14B-Q4_K_M.gguf"
+context_length = 4096
+temperature = 0.2
+top_p = 0.95
+top_k = 40
+enable_thinking = true
+
+[performance]
+threads = 8
+gpu_layers = 1
+
+[tools]
+code_interpreter = true
+shell = false
+search = false
+
+[paths]
+python_tool = "python"
+search_api_key = ""

agent/config/agent_config.toml

@@ -0,0 +1,21 @@
+from pymoo.algorithms.moo.nsga2 import NSGA2
+from pymoo.factory import get_sampling, get_crossover, get_mutation
+from pymoo.optimize import minimize
+
+from agent.tools import run_code_variant, CODE_TESTS
+
+
+def evolve(initial_code: str, pop_size: int = 8, gens: int = 6):
+    def fitness(code: str):
+        ok, runtime = run_code_variant(code, tests=CODE_TESTS)
+        return [-int(ok), runtime]
+
+    # Placeholder for population creation and NSGA-II execution
+    algo = NSGA2(
+        pop_size=pop_size,
+        sampling=get_sampling("int_random"),
+        crossover=get_crossover("int_sbx"),
+        mutation=get_mutation("int_pm"),
+    )
+    # Additional code needed to define the Problem and run minimize
+    # TODO: implement full evolution loop

agent/evolution/nsga.py

@@ -0,0 +1,41 @@
+import tomllib
+import time
+import os
+from pathlib import Path
+from llama_cpp import Llama
+from qwen_agent import Assistant
+from agent.tools import build_tools
+
+CFG_PATH = os.environ.get("AGENT_CONFIG", Path(__file__).with_suffix('.toml'))
+CFG = tomllib.loads(Path(CFG_PATH).read_text())
+
+os.environ["OMP_NUM_THREADS"] = str(CFG["performance"]["threads"])
+
+llm = Llama(
+    model_path=CFG["model"]["gguf_path"],
+    n_ctx=CFG["model"]["context_length"],
+    n_gpu_layers=CFG["performance"]["gpu_layers"],
+    temperature=CFG["model"]["temperature"],
+    top_p=CFG["model"]["top_p"],
+    top_k=CFG["model"]["top_k"],
+    logits_all=False,
+)
+
+assistant = Assistant(
+    llm=llm,
+    function_list=build_tools(CFG["tools"], CFG.get("paths", {})),
+    enable_thinking=CFG["model"]["enable_thinking"],
+)
+
+def chat(prompt: str) -> str:
+    start = time.perf_counter()
+    rsp = assistant.chat(prompt)["content"]
+    print(f"[{(time.perf_counter()-start):.2f}s]")
+    return rsp
+
+if __name__ == "__main__":
+    while True:
+        try:
+            print(chat(input(">>> ")))
+        except (EOFError, KeyboardInterrupt):
+            break

agent/main.py

@@ -0,0 +1,26 @@
+from typing import Dict, List
+
+from .code_interpreter import CodeInterpreterTool
+from .shell import ShellTool
+from .fetch import FetchTool
+
+
+def build_tools(cfg: Dict[str, bool], paths: Dict[str, str]) -> List[dict]:
+    tools = []
+    if cfg.get("code_interpreter"):
+        tools.append(CodeInterpreterTool(paths.get("python_tool", "python")))
+    if cfg.get("shell"):
+        tools.append(ShellTool())
+    if cfg.get("search"):
+        tools.append(FetchTool(paths.get("search_api_key", "")))
+    return [t.as_mcp() for t in tools]
+
+CODE_TESTS: str = """def test_add():\n    assert add(2,2) == 4\n"""
+
+
+def run_code_variant(code: str, tests: str = CODE_TESTS):
+    full_code = code + "\n" + tests + "\nif __name__ == '__main__':\n    import pytest, sys; sys.exit(pytest.main(['-q']))\n"
+    tool = CodeInterpreterTool()
+    output = tool.run(full_code)
+    success = '1 passed' in output
+    return success, 0.0

agent/tools/__init__.py

@@ -0,0 +1,27 @@
+import subprocess
+import tempfile
+from pathlib import Path
+
+class CodeInterpreterTool:
+    def __init__(self, python_path: str = "python"):
+        self.python_path = python_path
+
+    def as_mcp(self) -> dict:
+        return {
+            "name": "code_interpreter",
+            "description": "Execute Python code in a sandboxed environment",
+            "parameters": {"type": "string", "name": "code"},
+            "call": self.run,
+        }
+
+    def run(self, code: str) -> str:
+        with tempfile.TemporaryDirectory() as tmp:
+            p = subprocess.run(
+                [self.python_path, "-I", "-S", "-"],
+                input=code.encode(),
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                cwd=tmp,
+                timeout=10,
+            )
+            return p.stdout.decode()

agent/tools/code_interpreter.py

@@ -0,0 +1,20 @@
+import requests
+
+class FetchTool:
+    def __init__(self, api_key: str = ""):
+        self.api_key = api_key
+
+    def as_mcp(self) -> dict:
+        return {
+            "name": "search",
+            "description": "Fetch a web page or search result",
+            "parameters": {"type": "string", "name": "query"},
+            "call": self.run,
+        }
+
+    def run(self, query: str) -> str:
+        if not self.api_key:
+            return "offline"
+        r = requests.get("https://api.duckduckgo.com", params={"q": query, "format": "json"}, timeout=5)
+        data = r.json()
+        return data.get("Abstract", "")