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.
- llm_harness_lite-0.1.0a1/.dockerignore +6 -0
- llm_harness_lite-0.1.0a1/.env.example +7 -0
- llm_harness_lite-0.1.0a1/.github/workflows/publish-pypi.yml +25 -0
- llm_harness_lite-0.1.0a1/.gitignore +5 -0
- llm_harness_lite-0.1.0a1/.harness_cache.db +0 -0
- llm_harness_lite-0.1.0a1/Dockerfile +9 -0
- llm_harness_lite-0.1.0a1/LICENSE +21 -0
- llm_harness_lite-0.1.0a1/LOCAL_SETUP.md +43 -0
- llm_harness_lite-0.1.0a1/PKG-INFO +65 -0
- llm_harness_lite-0.1.0a1/README.md +38 -0
- llm_harness_lite-0.1.0a1/config.yaml +34 -0
- llm_harness_lite-0.1.0a1/docker-compose.yml +14 -0
- llm_harness_lite-0.1.0a1/examples/01_basic_chat.py +12 -0
- llm_harness_lite-0.1.0a1/examples/02_agent_with_tools.py +28 -0
- llm_harness_lite-0.1.0a1/examples/03_rag_ingest_search.py +27 -0
- llm_harness_lite-0.1.0a1/examples/04_cost_compare.py +21 -0
- llm_harness_lite-0.1.0a1/examples/05_qdrant_mcp_cache.py +44 -0
- llm_harness_lite-0.1.0a1/pyproject.toml +34 -0
- llm_harness_lite-0.1.0a1/src/harness/__init__.py +24 -0
- llm_harness_lite-0.1.0a1/src/llm_harness_lite/__init__.py +10 -0
- llm_harness_lite-0.1.0a1/src/llm_harness_lite/agent/__init__.py +0 -0
- llm_harness_lite-0.1.0a1/src/llm_harness_lite/agent/loop.py +46 -0
- llm_harness_lite-0.1.0a1/src/llm_harness_lite/llm/__init__.py +0 -0
- llm_harness_lite-0.1.0a1/src/llm_harness_lite/llm/anthropic_backend.py +55 -0
- llm_harness_lite-0.1.0a1/src/llm_harness_lite/llm/base.py +9 -0
- llm_harness_lite-0.1.0a1/src/llm_harness_lite/llm/factory.py +20 -0
- llm_harness_lite-0.1.0a1/src/llm_harness_lite/llm/openai_compat.py +48 -0
- llm_harness_lite-0.1.0a1/src/llm_harness_lite/llm/types.py +47 -0
- llm_harness_lite-0.1.0a1/src/llm_harness_lite/mcp/__init__.py +0 -0
- llm_harness_lite-0.1.0a1/src/llm_harness_lite/mcp/client.py +159 -0
- llm_harness_lite-0.1.0a1/src/llm_harness_lite/rag/__init__.py +0 -0
- llm_harness_lite-0.1.0a1/src/llm_harness_lite/rag/chunker.py +19 -0
- llm_harness_lite-0.1.0a1/src/llm_harness_lite/rag/embedder.py +28 -0
- llm_harness_lite-0.1.0a1/src/llm_harness_lite/rag/retriever.py +35 -0
- llm_harness_lite-0.1.0a1/src/llm_harness_lite/rag/store_base.py +30 -0
- llm_harness_lite-0.1.0a1/src/llm_harness_lite/rag/store_pgvector.py +51 -0
- llm_harness_lite-0.1.0a1/src/llm_harness_lite/rag/store_qdrant.py +58 -0
- llm_harness_lite-0.1.0a1/src/llm_harness_lite/tools/__init__.py +0 -0
- llm_harness_lite-0.1.0a1/src/llm_harness_lite/tools/registry.py +52 -0
- llm_harness_lite-0.1.0a1/src/llm_harness_lite/utils/__init__.py +0 -0
- llm_harness_lite-0.1.0a1/src/llm_harness_lite/utils/cache.py +143 -0
- llm_harness_lite-0.1.0a1/src/llm_harness_lite/utils/costs.py +16 -0
- llm_harness_lite-0.1.0a1/tests/__init__.py +0 -0
- llm_harness_lite-0.1.0a1/tests/test_addons.py +85 -0
- llm_harness_lite-0.1.0a1/tests/test_types.py +15 -0
|
@@ -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
|
|
Binary file
|
|
@@ -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"
|
|
File without changes
|
|
@@ -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)
|
|
File without changes
|
|
@@ -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"))
|