llm-harness-lite 0.1.0a1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. llm_harness_lite-0.1.0a1/.dockerignore +6 -0
  2. llm_harness_lite-0.1.0a1/.env.example +7 -0
  3. llm_harness_lite-0.1.0a1/.github/workflows/publish-pypi.yml +25 -0
  4. llm_harness_lite-0.1.0a1/.gitignore +5 -0
  5. llm_harness_lite-0.1.0a1/.harness_cache.db +0 -0
  6. llm_harness_lite-0.1.0a1/Dockerfile +9 -0
  7. llm_harness_lite-0.1.0a1/LICENSE +21 -0
  8. llm_harness_lite-0.1.0a1/LOCAL_SETUP.md +43 -0
  9. llm_harness_lite-0.1.0a1/PKG-INFO +65 -0
  10. llm_harness_lite-0.1.0a1/README.md +38 -0
  11. llm_harness_lite-0.1.0a1/config.yaml +34 -0
  12. llm_harness_lite-0.1.0a1/docker-compose.yml +14 -0
  13. llm_harness_lite-0.1.0a1/examples/01_basic_chat.py +12 -0
  14. llm_harness_lite-0.1.0a1/examples/02_agent_with_tools.py +28 -0
  15. llm_harness_lite-0.1.0a1/examples/03_rag_ingest_search.py +27 -0
  16. llm_harness_lite-0.1.0a1/examples/04_cost_compare.py +21 -0
  17. llm_harness_lite-0.1.0a1/examples/05_qdrant_mcp_cache.py +44 -0
  18. llm_harness_lite-0.1.0a1/pyproject.toml +34 -0
  19. llm_harness_lite-0.1.0a1/src/harness/__init__.py +24 -0
  20. llm_harness_lite-0.1.0a1/src/llm_harness_lite/__init__.py +10 -0
  21. llm_harness_lite-0.1.0a1/src/llm_harness_lite/agent/__init__.py +0 -0
  22. llm_harness_lite-0.1.0a1/src/llm_harness_lite/agent/loop.py +46 -0
  23. llm_harness_lite-0.1.0a1/src/llm_harness_lite/llm/__init__.py +0 -0
  24. llm_harness_lite-0.1.0a1/src/llm_harness_lite/llm/anthropic_backend.py +55 -0
  25. llm_harness_lite-0.1.0a1/src/llm_harness_lite/llm/base.py +9 -0
  26. llm_harness_lite-0.1.0a1/src/llm_harness_lite/llm/factory.py +20 -0
  27. llm_harness_lite-0.1.0a1/src/llm_harness_lite/llm/openai_compat.py +48 -0
  28. llm_harness_lite-0.1.0a1/src/llm_harness_lite/llm/types.py +47 -0
  29. llm_harness_lite-0.1.0a1/src/llm_harness_lite/mcp/__init__.py +0 -0
  30. llm_harness_lite-0.1.0a1/src/llm_harness_lite/mcp/client.py +159 -0
  31. llm_harness_lite-0.1.0a1/src/llm_harness_lite/rag/__init__.py +0 -0
  32. llm_harness_lite-0.1.0a1/src/llm_harness_lite/rag/chunker.py +19 -0
  33. llm_harness_lite-0.1.0a1/src/llm_harness_lite/rag/embedder.py +28 -0
  34. llm_harness_lite-0.1.0a1/src/llm_harness_lite/rag/retriever.py +35 -0
  35. llm_harness_lite-0.1.0a1/src/llm_harness_lite/rag/store_base.py +30 -0
  36. llm_harness_lite-0.1.0a1/src/llm_harness_lite/rag/store_pgvector.py +51 -0
  37. llm_harness_lite-0.1.0a1/src/llm_harness_lite/rag/store_qdrant.py +58 -0
  38. llm_harness_lite-0.1.0a1/src/llm_harness_lite/tools/__init__.py +0 -0
  39. llm_harness_lite-0.1.0a1/src/llm_harness_lite/tools/registry.py +52 -0
  40. llm_harness_lite-0.1.0a1/src/llm_harness_lite/utils/__init__.py +0 -0
  41. llm_harness_lite-0.1.0a1/src/llm_harness_lite/utils/cache.py +143 -0
  42. llm_harness_lite-0.1.0a1/src/llm_harness_lite/utils/costs.py +16 -0
  43. llm_harness_lite-0.1.0a1/tests/__init__.py +0 -0
  44. llm_harness_lite-0.1.0a1/tests/test_addons.py +85 -0
  45. llm_harness_lite-0.1.0a1/tests/test_types.py +15 -0
@@ -0,0 +1,6 @@
1
+ __pycache__
2
+ .venv
3
+ .env
4
+ .git
5
+ *.pyc
6
+ .harness_cache.db
@@ -0,0 +1,7 @@
1
+ OPENAI_API_KEY=
2
+ ANTHROPIC_API_KEY=
3
+ OPENROUTER_API_KEY=
4
+ DATABASE_URL=postgresql://harness:harness@localhost:5432/harness
5
+ LLM_PROVIDER=openai_compat
6
+ LLM_MODEL=qwen3:8b
7
+ LLM_BASE_URL=http://localhost:11434/v1
@@ -0,0 +1,25 @@
1
+ name: publish-pypi
2
+ # Trusted Publishing (OIDC, no API token needed).
3
+ # One-time setup: PyPI > your project > Settings > Publishing > Add GitHub publisher:
4
+ # owner = abadiape, repo = llm-harness-lite, workflow = publish-pypi.yml, env = pypi
5
+ # Then: git tag v0.1.0a1 && git push --tags -> builds + uploads to PyPI, reserves the name.
6
+ on:
7
+ push:
8
+ tags: ["v*"]
9
+ workflow_dispatch:
10
+
11
+ permissions:
12
+ contents: read
13
+ id-token: write # required for OIDC
14
+
15
+ jobs:
16
+ build-and-publish:
17
+ runs-on: ubuntu-latest
18
+ steps:
19
+ - uses: actions/checkout@v4
20
+ - uses: actions/setup-python@v5
21
+ with:
22
+ python-version: "3.15"
23
+ - run: pip install -U build
24
+ - run: python -m build
25
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,5 @@
1
+ __pycache__/
2
+ .venv/
3
+ .env
4
+ dist/
5
+ *.egg-info/
@@ -0,0 +1,9 @@
1
+ # App image for prod / collaborators who want full-docker. For daily dev, use venv + compose db only.
2
+ FROM python:3.15-slim
3
+ WORKDIR /app
4
+ COPY pyproject.toml README.md ./
5
+ COPY src/ src/
6
+ RUN pip install --no-cache-dir -e ".[dev]" && pip install --no-cache-dir qdrant-client ollama
7
+ COPY config.yaml .env.example ./
8
+ COPY examples/ examples/
9
+ CMD ["python", "examples/01_basic_chat.py"]
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 llm-harness-lite Pedro Abadía
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,43 @@
1
+ # Local setup (recommended: venv + compose for infra only)
2
+
3
+ You do NOT need a Dockerfile for daily dev. `docker-compose.yml` already pulls
4
+ prebuilt images (pgvector, qdrant). Your Python code runs on the host in a venv
5
+ for fast iteration.
6
+
7
+ ## 1) Infra with Docker (one command)
8
+ ```bash
9
+ docker compose up -d db qdrant
10
+ docker ps # 5432 = pgvector, 6333 = qdrant
11
+ ```
12
+
13
+ ## 2) Python in venv (host)
14
+ ```bash
15
+ python3 -m venv .venv
16
+ source .venv/bin/activate # Windows: .venv\Scripts\activate
17
+ pip install -U pip
18
+ pip install -e ".[dev]"
19
+ pip install -e ".[full]" 2>/dev/null || pip install qdrant-client ollama
20
+ cp .env.example .env
21
+ ```
22
+ Set the relevant API key in `.env` when using a hosted provider, such as
23
+ `OPENAI_API_KEY` for OpenAI. Ollama does not require an API key.
24
+
25
+ ## 3) Local models (cheapest path)
26
+ ```bash
27
+ ollama pull qwen3:8b
28
+ ollama pull nomic-embed-text
29
+ ```
30
+
31
+ ## 4) Run
32
+ ```bash
33
+ python examples/01_basic_chat.py
34
+ python examples/03_rag_ingest_search.py
35
+ python examples/05_qdrant_mcp_cache.py
36
+ ```
37
+
38
+ ## When to use the Dockerfile?
39
+ Only for prod deploy or sharing an exact env:
40
+ ```bash
41
+ docker build -t universal-harness .
42
+ docker run --network host --env-file .env universal-harness
43
+ ```
@@ -0,0 +1,65 @@
1
+ Metadata-Version: 2.5
2
+ Name: llm-harness-lite
3
+ Version: 0.1.0a1
4
+ Summary: LLM Harness Lite — lightweight universal agent + RAG + MCP for any LLM (local-first, cost-aware)
5
+ License: MIT
6
+ License-File: LICENSE
7
+ Requires-Python: >=3.10
8
+ Requires-Dist: anthropic>=0.40.0
9
+ Requires-Dist: mcp>=1.0.0
10
+ Requires-Dist: openai>=1.30.0
11
+ Requires-Dist: pgvector>=0.3.5
12
+ Requires-Dist: psycopg[binary]>=3.1
13
+ Requires-Dist: python-dotenv>=1.0.0
14
+ Requires-Dist: pyyaml>=6.0
15
+ Requires-Dist: tiktoken>=0.7.0
16
+ Provides-Extra: dev
17
+ Requires-Dist: pytest>=8.0; extra == 'dev'
18
+ Requires-Dist: ruff>=0.4.0; extra == 'dev'
19
+ Provides-Extra: full
20
+ Requires-Dist: ollama>=0.2.0; extra == 'full'
21
+ Requires-Dist: qdrant-client>=1.9.0; extra == 'full'
22
+ Provides-Extra: ollama-embed
23
+ Requires-Dist: ollama>=0.2.0; extra == 'ollama-embed'
24
+ Provides-Extra: qdrant
25
+ Requires-Dist: qdrant-client>=1.9.0; extra == 'qdrant'
26
+ Description-Content-Type: text/markdown
27
+
28
+ # LLM Harness Lite — lightweight universal agent + RAG + MCP for any LLM
29
+
30
+ Local-first, vendor-neutral, cost-aware. Not the next LangChain: ~1k LOC core you can read in an afternoon.
31
+
32
+ ```
33
+ config.yaml → llm/factory → agent/loop → tools/registry (+ RAG as tool, MCP tools)
34
+ ```
35
+
36
+ ## Install
37
+ ```bash
38
+ pip install llm-harness-lite
39
+ # or local dev:
40
+ # python -m venv .venv && source .venv/bin/activate
41
+ # pip install -e ".[dev]"
42
+ # docker compose up -d db qdrant
43
+ ```
44
+
45
+ ## Use (short alias supported)
46
+ ```python
47
+ import llm_harness_lite as harness
48
+ llm = harness.create_llm("openai_compat", "qwen3:8b", base_url="http://localhost:11434/v1")
49
+ ```
50
+
51
+ See `LOCAL_SETUP.md` + `examples/`:
52
+ - `01_basic_chat.py` — normalized `chat()` across providers
53
+ - `02_agent_with_tools.py` — agent loop + budget guard
54
+ - `03_rag_ingest_search.py` — pgvector RAG
55
+ - `04_cost_compare.py` — bang-for-buck across models
56
+ - `05_qdrant_mcp_cache.py` — Qdrant + persistent MCP + semantic cache
57
+
58
+ ## Layout (for contributors)
59
+ - `src/llm_harness_lite/llm/` — `types.py`, `base.py` (Protocol), `openai_compat.py`, `anthropic_backend.py`, `factory.py`
60
+ - `src/llm_harness_lite/agent/loop.py` — framework-agnostic ReAct loop
61
+ - `src/llm_harness_lite/tools/registry.py` — `@tool` + JSON Schema from signature
62
+ - `src/llm_harness_lite/rag/` — `chunker.py`, `embedder.py`, `store_base.py`, `store_pgvector.py`, `store_qdrant.py`, `retriever.py`
63
+ - `src/llm_harness_lite/mcp/client.py` — `MCPClient` + `PersistentMCP` background-loop bridge
64
+ - `src/llm_harness_lite/utils/` — `costs.py`, `cache.py` (exact + semantic)
65
+ - `src/harness/` — back-compat shim (`import harness` still works)
@@ -0,0 +1,38 @@
1
+ # LLM Harness Lite — lightweight universal agent + RAG + MCP for any LLM
2
+
3
+ Local-first, vendor-neutral, cost-aware. Not the next LangChain: ~1k LOC core you can read in an afternoon.
4
+
5
+ ```
6
+ config.yaml → llm/factory → agent/loop → tools/registry (+ RAG as tool, MCP tools)
7
+ ```
8
+
9
+ ## Install
10
+ ```bash
11
+ pip install llm-harness-lite
12
+ # or local dev:
13
+ # python -m venv .venv && source .venv/bin/activate
14
+ # pip install -e ".[dev]"
15
+ # docker compose up -d db qdrant
16
+ ```
17
+
18
+ ## Use (short alias supported)
19
+ ```python
20
+ import llm_harness_lite as harness
21
+ llm = harness.create_llm("openai_compat", "qwen3:8b", base_url="http://localhost:11434/v1")
22
+ ```
23
+
24
+ See `LOCAL_SETUP.md` + `examples/`:
25
+ - `01_basic_chat.py` — normalized `chat()` across providers
26
+ - `02_agent_with_tools.py` — agent loop + budget guard
27
+ - `03_rag_ingest_search.py` — pgvector RAG
28
+ - `04_cost_compare.py` — bang-for-buck across models
29
+ - `05_qdrant_mcp_cache.py` — Qdrant + persistent MCP + semantic cache
30
+
31
+ ## Layout (for contributors)
32
+ - `src/llm_harness_lite/llm/` — `types.py`, `base.py` (Protocol), `openai_compat.py`, `anthropic_backend.py`, `factory.py`
33
+ - `src/llm_harness_lite/agent/loop.py` — framework-agnostic ReAct loop
34
+ - `src/llm_harness_lite/tools/registry.py` — `@tool` + JSON Schema from signature
35
+ - `src/llm_harness_lite/rag/` — `chunker.py`, `embedder.py`, `store_base.py`, `store_pgvector.py`, `store_qdrant.py`, `retriever.py`
36
+ - `src/llm_harness_lite/mcp/client.py` — `MCPClient` + `PersistentMCP` background-loop bridge
37
+ - `src/llm_harness_lite/utils/` — `costs.py`, `cache.py` (exact + semantic)
38
+ - `src/harness/` — back-compat shim (`import harness` still works)
@@ -0,0 +1,34 @@
1
+ llm:
2
+ provider: openai_compat # openai_compat | openai | anthropic | openrouter
3
+ model: qwen3:8b
4
+ base_url: http://localhost:11434/v1
5
+ api_key: dummy
6
+ temperature: 0.2
7
+ embed:
8
+ provider: ollama # openai | ollama
9
+ model: nomic-embed-text
10
+ base_url: http://localhost:11434
11
+ store:
12
+ kind: pgvector # pgvector | qdrant (same Retriever API)
13
+ pgvector:
14
+ dsn: postgresql://harness:harness@localhost:5432/harness
15
+ table: rag_chunks
16
+ dim: 768
17
+ qdrant:
18
+ url: http://localhost:6333
19
+ collection: rag_chunks
20
+ dim: 768
21
+ rag:
22
+ chunk_size: 600
23
+ chunk_overlap: 80
24
+ top_k_vector: 20
25
+ top_k_final: 5
26
+ cache:
27
+ path: .harness_cache.db
28
+ semantic_threshold: 0.93
29
+ enabled: true
30
+ agent:
31
+ max_steps: 8
32
+ budget_usd: 0.05
33
+ mcp:
34
+ servers: [] # e.g. [{command: "npx", args: ["-y","@modelcontextprotocol/server-filesystem","/tmp"]}]
@@ -0,0 +1,14 @@
1
+ services:
2
+ db:
3
+ image: pgvector/pgvector:pg16
4
+ environment:
5
+ POSTGRES_USER: harness
6
+ POSTGRES_PASSWORD: harness
7
+ POSTGRES_DB: harness
8
+ ports: ["5432:5432"]
9
+ volumes: [pgdata:/var/lib/postgresql/data]
10
+ qdrant:
11
+ image: qdrant/qdrant:latest
12
+ ports: ["6333:6333", "6334:6334"]
13
+ volumes: [qdrant_data:/qdrant/storage]
14
+ volumes: {pgdata: {}, qdrant_data: {}}
@@ -0,0 +1,12 @@
1
+ """Normalized chat() — swap provider via config.yaml / env."""
2
+ import os, yaml
3
+ from dotenv import load_dotenv
4
+ load_dotenv()
5
+ import llm_harness_lite as harness
6
+
7
+ cfg = yaml.safe_load(open("config.yaml"))
8
+ llm = harness.create_llm(cfg["llm"]["provider"], cfg["llm"]["model"],
9
+ base_url=cfg["llm"].get("base_url"))
10
+ resp = llm.chat([harness.Message(role="user", content="Say hello in one line + name your model.")])
11
+ print(resp.message.content)
12
+ print(f"[tokens {resp.usage.input_tokens}/{resp.usage.output_tokens} | ${resp.usage.cost_usd:.5f}]")
@@ -0,0 +1,28 @@
1
+ """Agent loop with local python tools + RAG-as-tool pattern."""
2
+ import yaml
3
+ from dotenv import load_dotenv
4
+ load_dotenv()
5
+ import llm_harness_lite as harness
6
+
7
+ cfg = yaml.safe_load(open("config.yaml"))
8
+ llm = harness.create_llm(cfg["llm"]["provider"], cfg["llm"]["model"],
9
+ base_url=cfg["llm"].get("base_url"))
10
+ reg = harness.ToolRegistry()
11
+
12
+ @harness.tool(reg)
13
+ def calc(expr: str) -> str:
14
+ """Evaluate a math expression. Args: expr like '12*7'."""
15
+ allowed = set("0123456789+-*/(). ")
16
+ assert set(expr) <= allowed, "unsafe chars"
17
+ return str(eval(expr))
18
+
19
+ @harness.tool(reg)
20
+ def search_docs(query: str) -> str:
21
+ """Search ingested docs. Replace body with Retriever.context_block()."""
22
+ return f"[stub] would retrieve for: {query}"
23
+
24
+ agent = harness.Agent(llm, reg, max_steps=cfg["agent"]["max_steps"],
25
+ budget_usd=cfg["agent"]["budget_usd"])
26
+ res = agent.run("What is 18*23? Then search_docs for 'refunds'. Answer concisely.")
27
+ print(res.answer)
28
+ print(f"[steps {res.steps} | ${res.usage.cost_usd:.5f} | {res.usage.input_tokens+res.usage.output_tokens} tok]")
@@ -0,0 +1,27 @@
1
+ """RAG starter: ingest a file → configured vector store → search → inject into prompt."""
2
+ import yaml
3
+ from dotenv import load_dotenv
4
+ load_dotenv()
5
+ import llm_harness_lite as harness
6
+ from llm_harness_lite.rag.embedder import OllamaEmbedder, OpenAIEmbedder
7
+ from llm_harness_lite.rag.store_base import create_store
8
+ from llm_harness_lite.rag.retriever import Retriever
9
+
10
+ cfg = yaml.safe_load(open("config.yaml"))
11
+ ecfg = cfg["embed"]
12
+ emb = OllamaEmbedder(ecfg["model"], ecfg.get("base_url", "http://localhost:11434")) \
13
+ if ecfg["provider"] == "ollama" else OpenAIEmbedder(ecfg["model"])
14
+ store_cfg = cfg["store"][cfg["store"]["kind"]]
15
+ store = create_store(cfg["store"]["kind"], **store_cfg)
16
+ store.init()
17
+ ret = Retriever(emb, store, cfg["rag"]["chunk_size"], cfg["rag"]["chunk_overlap"])
18
+
19
+ text = open("README.md").read()
20
+ print(f"ingested {ret.ingest(text, source='README.md')} chunks")
21
+ q = "What does this harness do?"
22
+ ctx = ret.context_block(q, top_k=cfg["rag"]["top_k_final"])
23
+ llm = harness.create_llm(cfg["llm"]["provider"], cfg["llm"]["model"],
24
+ base_url=cfg["llm"].get("base_url"))
25
+ resp = llm.chat([harness.Message(role="system", content="Answer ONLY from CONTEXT. Cite [1][2]."),
26
+ harness.Message(role="user", content=f"CONTEXT:\n{ctx}\n\nQ: {q}")])
27
+ print(resp.message.content)
@@ -0,0 +1,21 @@
1
+ """Bang-for-buck: same prompt across backends, print tokens/$/latency."""
2
+ import time
3
+ from dotenv import load_dotenv
4
+ load_dotenv()
5
+
6
+ import llm_harness_lite as harness
7
+
8
+ MODELS = [
9
+ ("openai_compat", "qwen3:8b", {"base_url": "http://localhost:11434/v1"}),
10
+ ("openai", "gpt-4o-mini", {}),
11
+ # ("anthropic", "claude-3-5-haiku-latest", {}),
12
+ ]
13
+ prompt = "Explain pgvector vs Qdrant in 3 bullets for a Python dev."
14
+ for provider, model, kw in MODELS:
15
+ try:
16
+ llm = harness.create_llm(provider, model, **kw)
17
+ r = llm.chat([harness.Message(role="user", content=prompt)])
18
+ print(f"\n== {model} ==\n{r.message.content[:400]}")
19
+ print(f"tok {r.usage.input_tokens}/{r.usage.output_tokens} | ${r.usage.cost_usd:.5f} | {r.usage.latency_s:.1f}s")
20
+ except Exception as e:
21
+ print(f"\n== {model} FAILED: {e}")
@@ -0,0 +1,44 @@
1
+ """All three add-ons together: Qdrant store + persistent MCP + semantic cache.
2
+
3
+ Run: docker compose up -d qdrant ; python examples/05_qdrant_mcp_cache.py
4
+ """
5
+ import yaml
6
+ from dotenv import load_dotenv
7
+ load_dotenv()
8
+
9
+ import llm_harness_lite as harness
10
+ from llm_harness_lite.rag.embedder import OllamaEmbedder
11
+ from llm_harness_lite.rag.store_base import create_store
12
+ from llm_harness_lite.rag.retriever import Retriever
13
+ from llm_harness_lite.utils.cache import ChatCache, CachedLLM
14
+ from llm_harness_lite.mcp.client import PersistentMCP
15
+
16
+ cfg = yaml.safe_load(open("config.yaml"))
17
+
18
+ # 1) Qdrant store (swap kind to pgvector in config to compare)
19
+ s = cfg["store"]["qdrant"]
20
+ store = create_store("qdrant", url=s["url"], collection=s["collection"], dim=s["dim"])
21
+ store.init()
22
+ emb = OllamaEmbedder(cfg["embed"]["model"], cfg["embed"]["base_url"])
23
+ ret = Retriever(emb, store)
24
+ ret.ingest("Qdrant is a Rust vector DB with hybrid dense+sparse search.", source="docs")
25
+ print("Qdrant search:", ret.context_block("What is Qdrant?", top_k=2)[:200])
26
+
27
+ # 2) Cached LLM (exact + semantic)
28
+ base = harness.create_llm(cfg["llm"]["provider"], cfg["llm"]["model"], base_url=cfg["llm"].get("base_url"))
29
+ llm = CachedLLM(base, ChatCache(cfg["cache"]["path"]), embedder=emb,
30
+ semantic_threshold=cfg["cache"]["semantic_threshold"])
31
+ for i in range(2): # second call should hit cache
32
+ r = llm.chat([harness.Message(role="user", content="What is Qdrant in one line?")])
33
+ print(f"call{i}: {r.message.content[:120]} | model={r.usage.model}")
34
+ print("cache stats:", llm.stats())
35
+
36
+ # 3) Persistent MCP (needs an MCP server; skipped if none configured)
37
+ servers = cfg.get("mcp", {}).get("servers", [])
38
+ if servers:
39
+ reg = harness.ToolRegistry()
40
+ m = PersistentMCP(command=servers[0]["command"], args=servers[0].get("args", [])).start()
41
+ print("MCP tools:", m.register_into(reg))
42
+ m.stop()
43
+ else:
44
+ print("MCP: no servers in config.yaml -> skipped (add one to test).")
@@ -0,0 +1,34 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "llm-harness-lite"
7
+ version = "0.1.0a1"
8
+ license = { text = "MIT" }
9
+ description = "LLM Harness Lite — lightweight universal agent + RAG + MCP for any LLM (local-first, cost-aware)"
10
+ readme = "README.md"
11
+ requires-python = ">=3.10"
12
+ dependencies = [
13
+ "openai>=1.30.0",
14
+ "anthropic>=0.40.0",
15
+ "psycopg[binary]>=3.1",
16
+ "pgvector>=0.3.5",
17
+ "pyyaml>=6.0",
18
+ "tiktoken>=0.7.0",
19
+ "mcp>=1.0.0",
20
+ "python-dotenv>=1.0.0",
21
+ ]
22
+
23
+ [project.optional-dependencies]
24
+ dev = ["pytest>=8.0", "ruff>=0.4.0"]
25
+ qdrant = ["qdrant-client>=1.9.0"]
26
+ full = ["qdrant-client>=1.9.0", "ollama>=0.2.0"]
27
+ ollama-embed = ["ollama>=0.2.0"]
28
+
29
+ [tool.hatch.build.targets.wheel]
30
+ packages = ["src/llm_harness_lite", "src/harness"]
31
+
32
+ [tool.ruff]
33
+ line-length = 100
34
+ target-version = "py310"
@@ -0,0 +1,24 @@
1
+ """Back-compat: `import harness` is an alias of `llm_harness_lite`.
2
+
3
+ New code should use `import llm_harness_lite as harness`.
4
+ Old deep imports (`from harness.llm.types import X`) keep working and
5
+ resolve to the SAME objects (no duplicate-class bugs).
6
+ """
7
+ import sys as _sys
8
+ import importlib as _il
9
+
10
+ import llm_harness_lite as _m
11
+ _sys.modules[__name__] = _m
12
+
13
+ # Alias submodules so harness.X is llm_harness_lite.X (same object)
14
+ _SUBS = ["llm", "llm.types", "llm.base", "llm.factory", "llm.openai_compat",
15
+ "llm.anthropic_backend", "agent", "agent.loop", "tools", "tools.registry",
16
+ "rag", "rag.chunker", "rag.embedder", "rag.store_base",
17
+ "rag.store_pgvector", "rag.store_qdrant", "rag.retriever",
18
+ "mcp", "mcp.client", "utils", "utils.costs", "utils.cache"]
19
+ for _s in _SUBS:
20
+ try:
21
+ _mod = _il.import_module(f"llm_harness_lite.{_s}")
22
+ _sys.modules[f"harness.{_s}"] = _mod
23
+ except Exception:
24
+ pass
@@ -0,0 +1,10 @@
1
+ """LLM Harness Lite — lightweight universal agent + RAG + MCP for any model."""
2
+ from llm_harness_lite.llm.types import ChatResponse, Message, ToolCallRequest, ToolSpec
3
+ from llm_harness_lite.llm.factory import create_llm
4
+ from llm_harness_lite.agent.loop import Agent, AgentResult
5
+ from llm_harness_lite.tools.registry import ToolRegistry, tool
6
+
7
+ # Short alias for code: `import llm_harness_lite as harness`
8
+ __all__ = ["ChatResponse", "Message", "ToolCallRequest", "ToolSpec",
9
+ "create_llm", "Agent", "AgentResult", "ToolRegistry", "tool"]
10
+ __version__ = "0.1.0a1"
@@ -0,0 +1,46 @@
1
+ """Framework-agnostic agent loop. Works with any LLMBackend."""
2
+ from __future__ import annotations
3
+ from dataclasses import dataclass, field
4
+ from llm_harness_lite.llm.types import Message, Usage
5
+
6
+ SYSTEM = ("You are a careful agent. Think step by step. "
7
+ "Call one tool at a time. When finished, answer WITHOUT further tool calls. "
8
+ "If a tool errors, try to recover or explain.")
9
+
10
+ @dataclass
11
+ class AgentResult:
12
+ answer: str
13
+ steps: int
14
+ usage: Usage
15
+ history: list[Message] = field(default_factory=list)
16
+
17
+ class Agent:
18
+ def __init__(self, llm, registry, max_steps: int = 8,
19
+ budget_usd: float = 0.05, system: str = SYSTEM):
20
+ self.llm, self.registry = llm, registry
21
+ self.max_steps, self.budget = max_steps, budget_usd
22
+ self.system = system
23
+
24
+ def run(self, goal: str, temperature: float = 0.2) -> AgentResult:
25
+ msgs = [Message(role="system", content=self.system),
26
+ Message(role="user", content=goal)]
27
+ total = Usage(model=getattr(self.llm, "model", ""))
28
+ for step in range(1, self.max_steps + 1):
29
+ resp = self.llm.chat(msgs, tools=self.registry.specs(), temperature=temperature)
30
+ total.input_tokens += resp.usage.input_tokens
31
+ total.output_tokens += resp.usage.output_tokens
32
+ total.cost_usd += resp.usage.cost_usd
33
+ total.latency_s += resp.usage.latency_s
34
+ msgs.append(resp.message)
35
+ if resp.finish != "tool_calls" or not resp.message.tool_calls:
36
+ return AgentResult(answer=resp.message.content, steps=step,
37
+ usage=total, history=msgs)
38
+ for tc in resp.message.tool_calls:
39
+ result = self.registry.call(tc.name, tc.arguments)
40
+ msgs.append(Message(role="tool", content=result[:8000],
41
+ tool_call_id=tc.id, name=tc.name))
42
+ if total.cost_usd > self.budget:
43
+ return AgentResult(answer="[BUDGET EXCEEDED] " + msgs[-2].content,
44
+ steps=step, usage=total, history=msgs)
45
+ return AgentResult(answer="[MAX STEPS] " + msgs[-1].content,
46
+ steps=self.max_steps, usage=total, history=msgs)
@@ -0,0 +1,55 @@
1
+ """Anthropic backend, translated to/from normalized types."""
2
+ from __future__ import annotations
3
+ import time
4
+ import anthropic
5
+ from llm_harness_lite.llm.types import ChatResponse, Message, ToolCallRequest, ToolSpec, Usage
6
+ from llm_harness_lite.utils.costs import estimate_cost
7
+
8
+ class AnthropicBackend:
9
+ def __init__(self, model: str):
10
+ self.model = model
11
+ self.client = anthropic.Anthropic()
12
+
13
+ def chat(self, messages: list[Message], tools: list[ToolSpec] | None = None,
14
+ temperature: float = 0.2) -> ChatResponse:
15
+ t0 = time.time()
16
+ system = "\n".join(m.content for m in messages if m.role == "system")
17
+ conv: list[dict] = []
18
+ for m in messages:
19
+ if m.role == "system":
20
+ continue
21
+ if m.role == "tool":
22
+ conv.append({"role": "user", "content": [
23
+ {"type": "tool_result", "tool_use_id": m.tool_call_id,
24
+ "content": m.content}]})
25
+ elif m.role == "assistant" and m.tool_calls:
26
+ blocks: list[dict] = []
27
+ if m.content:
28
+ blocks.append({"type": "text", "text": m.content})
29
+ blocks += [{"type": "tool_use", "id": tc.id, "name": tc.name,
30
+ "input": tc.arguments} for tc in m.tool_calls]
31
+ conv.append({"role": "assistant", "content": blocks})
32
+ else:
33
+ conv.append({"role": m.role, "content": m.content})
34
+ kwargs: dict = {"model": self.model, "max_tokens": 1024,
35
+ "temperature": temperature, "messages": conv}
36
+ if system:
37
+ kwargs["system"] = system
38
+ if tools:
39
+ kwargs["tools"] = [{"name": t.name, "description": t.description,
40
+ "input_schema": t.parameters} for t in tools]
41
+ resp = self.client.messages.create(**kwargs)
42
+ text, tcs = "", []
43
+ for b in resp.content:
44
+ if b.type == "text":
45
+ text += b.text
46
+ elif b.type == "tool_use":
47
+ tcs.append(ToolCallRequest(id=b.id, name=b.name, arguments=dict(b.input)))
48
+ return ChatResponse(
49
+ message=Message(role="assistant", content=text, tool_calls=tcs),
50
+ finish="tool_calls" if resp.stop_reason == "tool_use" else "stop",
51
+ usage=Usage(input_tokens=resp.usage.input_tokens,
52
+ output_tokens=resp.usage.output_tokens,
53
+ cost_usd=estimate_cost(self.model, resp.usage.input_tokens,
54
+ resp.usage.output_tokens),
55
+ model=self.model, latency_s=time.time() - t0))
@@ -0,0 +1,9 @@
1
+ """Backend contract. Every new provider implements this Protocol."""
2
+ from __future__ import annotations
3
+ from typing import Protocol
4
+ from llm_harness_lite.llm.types import ChatResponse, Message, ToolSpec
5
+
6
+ class LLMBackend(Protocol):
7
+ model: str
8
+ def chat(self, messages: list[Message], tools: list[ToolSpec] | None = None,
9
+ temperature: float = 0.2) -> ChatResponse: ...
@@ -0,0 +1,20 @@
1
+ """Add new providers here. Keep `create_llm` as the single entry point."""
2
+ from __future__ import annotations
3
+ import os
4
+
5
+ def create_llm(provider: str, model: str, **kw):
6
+ """provider: openai_compat | openai | openrouter | ollama | anthropic"""
7
+ if provider == "anthropic":
8
+ from llm_harness_lite.llm.anthropic_backend import AnthropicBackend
9
+ return AnthropicBackend(model)
10
+ if provider == "openai":
11
+ from llm_harness_lite.llm.openai_compat import OpenAICompatBackend
12
+ return OpenAICompatBackend(model, api_key=os.getenv("OPENAI_API_KEY"))
13
+ if provider == "openrouter":
14
+ from llm_harness_lite.llm.openai_compat import OpenAICompatBackend
15
+ return OpenAICompatBackend(model, base_url="https://openrouter.ai/api/v1",
16
+ api_key=os.getenv("OPENROUTER_API_KEY"))
17
+ # openai_compat covers ollama / vllm / lmstudio via base_url
18
+ from llm_harness_lite.llm.openai_compat import OpenAICompatBackend
19
+ return OpenAICompatBackend(model, base_url=kw.get("base_url"),
20
+ api_key=kw.get("api_key", "dummy"))