Skip to content
Back to search

reins

A lightweight agent harness you bolt onto your app so an LLM can operate it — safely, and cheaply.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/shamspias--reins/badge.svg)](/listings/shamspias--reins)

HTML

<a href="/listings/shamspias--reins"><img src="/api/listings/shamspias--reins/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Reins requires **Python 3.11+**.

pip install reins                 # core (first PyPI release coming soon)
pip install "reins[anthropic]"    # with the Anthropic backend
pip install "reins[openai]"       # with OpenAI / Gemini / Groq / Z.ai / Ollama / vLLM
pip install "reins[sqlalchemy]"   # with Agent.from_orm(...) for SQLAlchemy
pip install "reins[django]"       # with Agent.from_orm(...) for Django

Until the first published release, install from source:

git clone https://github.com/shamspias/reins
pip install -e "reins/packages/python[anthropic,openai]"
export ANTHROPIC_API_KEY=sk-...   # or any provider key from the table below

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 476 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Reins
  2. **A lightweight agent harness you bolt onto your app so an LLM can operate it — safely and cheaply.**
  3. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  4. [![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
  5. [![Status](https://img.shields.io/badge/status-alpha-orange.svg)](#status)
  6. Point Reins at functions you already have — or your ORM models — and hand it a goal in
  7. plain language. It works out which of your operations to call and in what order, runs
  8. them **through your own code (never raw SQL by default)**, and returns the result, with
  9. near-zero token overhead and safe-by-default writes. There is no graph to draw: you
  10. expose your app, and the agent operates it.
  11. > **The wedge: Reins gives the model your _verbs_, not your _tables_.**
  12. > Intent-named functions like `refund_order` carry the meaning that raw schemas and
  13. > OpenAPI specs strip away — which is exactly where text-to-SQL and auto-generated tool
  14. > layers lose their reliability.
  15. ## See it all at once
  16. ```bash
  17. git clone https://github.com/shamspias/reins && cd reins
  18. make setup && make demo
  19. ```
  20. `make demo` runs the flagship example (`examples/fastapi_sqlalchemy/`) — no API
  21. key needed. It auto-exposes a shop's SQLAlchemy models, answers a read question,
  22. scopes orders per logged-in user, pauses a write at an approval prompt, and prints
  23. the audit trail. `examples/fastapi_sqlalchemy/app.py` is the same agent as a real
  24. FastAPI server with the `<reins-chat>` widget.
  25. ## No code at all: point it at a database
  26. Already have a database? Operate it from your terminal — no models, no Python:
  27. ```bash
  28. pip install "reins[sqlalchemy]"
  29. export ANTHROPIC_API_KEY=sk-... # or any provider key
  30. reins inspect sqlite:///shop.db # see what Reins can do (no key needed)
  31. reins ask sqlite:///shop.db "how many orders shipped last week?"
  32. reins chat sqlite:///shop.db # an interactive, read-only Q&A session
  33. ```
  34. `reins chat` and `ask` are **read-only** — they answer questions but never change
  35. your data. `reins inspect` reflects your tables and prints the exact capability
  36. surface (with read/write classification) so you can see what an agent could do
  37. before you ever run one.
  38. ## The adoption ladder
  39. Start at the top rung and stop wherever you have what you need — each is a strict
  40. superset of the one above, and nothing lower ever requires the levels below it.
  41. | Level | You have… | You write… |
  42. | ----- | --------- | ---------- |
  43. | **0 — Try it** | a database | nothing — `make demo`, or `reins chat <db-url>` |
  44. | **1 — Your ORM** | SQLAlchemy / Django models | `Agent.from_orm(db, models=[...])` |
  45. | **2 — Your functions** | functions or a module | `@capability` / `Agent.from_module(mod)` |
  46. | **3 — Writes, safely** | something to change | `can_write=True`, `approve=`, `principal=` (RLS) |
  47. | **4 — Production** | users and traffic | a provider, `DockerSandbox()`, `endpoint(...)`, budgets |
  48. Full copy-paste walkthrough: **[QUICKSTART.md](QUICKSTART.md)**. Swapping in your
  49. own model, policy, approval gate, sandbox, or audit sink:
  50. **[EXTENDING.md](EXTENDING.md)**.
  51. ## Example
  52. ```python
  53. from reins import Agent, capability
  54. @capability
  55. def find_orders(status: str) -> list[dict]:
  56. """Find orders by their current status."""
  57. return store.orders(status=status) # your existing code
  58. @capability
  59. def refund_order(order_id: int) -> dict:
  60. """Refund a customer's order by its public order number."""
  61. return payments.refund(order_id) # your existing code
  62. agent = Agent(capabilities=[find_orders, refund_order])
  63. # ask() is read-only: it can never call a write capability.
  64. result = agent.ask("how many orders are stuck in processing?")
  65. print(result.output.text)
  66. # run() may write: writes are gated before they execute.
  67. agent.run("refund order 8842")
  68. ```
  69. The model is auto-detected from your environment (set any of `ANTHROPIC_API_KEY`,
  70. `OPENAI_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY`, `ZAI_API_KEY`), or named
  71. explicitly: `Agent(model="openai:gpt-4o")`, `Agent(model="ollama:llama3.1")`, or just
  72. `Agent(model="claude-opus-4-8")`.
  73. ### Already have an ORM? Skip the decorating.
  74. Point Reins at your **SQLAlchemy or Django** models and it generates the
  75. capabilities for you — intent-named verbs, not raw tables — with **zero
  76. hand-written code**:
  77. ```python
  78. from reins import Agent
  79. # SQLAlchemy: pass your Session / sessionmaker / Engine
  80. agent = Agent.from_orm(db, models=[User, Order]) # reads only, safe
  81. agent.ask("how many orders are still open for acme@corp.com?")
  82. # Django: no db argument — the connection is global
  83. agent = Agent.from_orm(models=[User, Order], can_write=True) # writes opt-in, gated
  84. agent.run("refund order 8842 and email the customer")
  85. ```
  86. Reins introspects each model into `find_orders` / `get_user_by_email` /
  87. `create_user` / … (lookups prefer a **unique** natural key like email over
  88. internal ids), builds a searchable schema index, trims every response so raw
  89. tables never flood the context, and runs it all through **your** ORM —
  90. inheriting your constraints and validation. The same `from_orm` works
  91. identically for SQLAlchemy and Django.
  92. ## Why Reins
  93. - **Your verbs, not your tables.** The model sees intent-named operations with real
  94. descriptions and types — not opaque columns or hand-written JSON schemas.
  95. - **Safe by default.** `ask()` is read-only and can never write; writes are opt-in and
  96. gated. Beginners cannot cause damage, and the boundary is enforced in code, not in a
  97. prompt the model can reason around.
  98. - **You hold the reins.** Reins runs *your* functions, so it inherits your existing
  99. validation, authorization, and business rules. No raw SQL against your database.
  100. - **Tiny and transparent.** The core is a small, readable loop you own — no hidden
  101. graph, no framework internals to reverse-engineer when you hit a ceiling. And
  102. `agent.explain()` shows exactly what it did: the code it wrote, every call, each
  103. result.
  104. - **Any model.** Anthropic, OpenAI, Gemini, Groq, Z.ai (GLM), and local servers
  105. (Ollama, vLLM) ship in the box; anything OpenAI-compatible works too.
  106. ## How it works
  107. 1. **Register.** Decorate the functions you want to expose. Reins reads their type hints
  108. and docstrings to derive a schema and classify each as read or write.
  109. 2. **Discover.** The agent is shown your intent-named operations and the goal.
  110. 3. **Plan.** It decides which operations to call, and in what order, to reach the goal.
  111. 4. **Govern.** Reads run freely; writes pass through policy, approval, and audit before
  112. anything touches your data.
  113. 5. **Return.** Only results cross back to the model, and every decision and call is
  114. traceable.
  115. ## Installation
  116. Reins requires **Python 3.11+**.
  117. ```bash
  118. pip install reins # core (first PyPI release coming soon)
  119. pip install "reins[anthropic]" # with the Anthropic backend
  120. pip install "reins[openai]" # with OpenAI / Gemini / Groq / Z.ai / Ollama / vLLM
  121. pip install "reins[sqlalchemy]" # with Agent.from_orm(...) for SQLAlchemy
  122. pip install "reins[django]" # with Agent.from_orm(...) for Django
  123. ```
  124. Until the first published release, install from source:
  125. ```bash
  126. git clone https://github.com/shamspias/reins
  127. pip install -e "reins/packages/python[anthropic,openai]"
  128. export ANTHROPIC_API_KEY=sk-... # or any provider key from the table below
  129. ```
  130. ## Bring any model
  131. One line picks the provider — everything else stays identical:
  132. ```python
  133. Agent(model="anthropic:claude-opus-4-8") # or just "claude-opus-4-8"
  134. Agent(model="openai:gpt-5.1") # or just "gpt-5.1"
  135. Agent(model="gemini:gemini-2.5-flash")
  136. Agent(model="groq:llama-3.3-70b-versatile")
  137. Agent(model="zai:glm-4.6") # Z.ai / GLM ("glm:..." works too)
  138. Agent(model="ollama:llama3.1") # local, no API key needed
  139. Agent(model="vllm:Qwen/Qwen2.5-72B") # your own vLLM server
  140. ```
  141. | Provider | Env var for the key | Notes |
  142. | -------- | ------------------- | ----- |
  143. | Anthropic | `ANTHROPIC_API_KEY` | native adapter |
  144. | OpenAI | `OPENAI_API_KEY` | `OPENAI_BASE_URL` points it at any compatible proxy |
  145. | Google Gemini | `GEMINI_API_KEY` | via Gemini's OpenAI-compatible endpoint |
  146. | Groq | `GROQ_API_KEY` | |
  147. | Z.ai (GLM) | `ZAI_API_KEY` | |
  148. | Ollama | — (none) | local; `OLLAMA_BASE_URL` overrides `http://localhost:11434/v1` |
  149. | vLLM | `VLLM_API_KEY` (optional) | `VLLM_BASE_URL` overrides `http://localhost:8000/v1` |
  150. With no `model=` at all, Reins auto-detects from the environment in that table's
  151. order. Every resolution failure tells you exactly what to set next.
  152. ## The two verbs
  153. Reins has exactly two entry points, and they *are* the safety model:
  154. - **`ask(goal)`** — the agent may only read. It never writes, never blocks, and never
  155. prompts. Use it for dashboards, search, analytics, and "what is…".
  156. - **`run(goal)`** — the agent may read and write. Writes are detected automatically and
  157. gated for approval. Use it for "do something": create, update, refund, send.
  158. Read/write classification is automatic and errs toward "write" when a name is ambiguous,
  159. so a wrong guess only ever adds a needless approval — it can never let a write slip
  160. through as a read. Override it explicitly when you know better:
  161. ```python
  162. @capability(reads=True)
  163. def export_report(month: str) -> bytes: ...
  164. @capability(destructive=True, confirm=True)
  165. def deactivate_user(user_id: int) -> None: ...
  166. ```
  167. ## Approvals: the human gate
  168. When `run()` reaches a write that needs approval, it pauses and shows you exactly
  169. what it wants to do before anything executes:
  170. ```
  171. ⚠ Reins wants to run a DESTRUCTIVE WRITE: refund_order(order_id=8842)
  172. Approve? [y]es / [n]o / [s]how
  173. ```
  174. `[s]how` reveals the unabridged calls and arguments as JSON. The gate **fails
  175. closed**: denying, running headless (no terminal), or an approval handler that
  176. crashes all mean the write does not run — and the attempt is recorded.
  177. The terminal prompt is just the default. Plug in your own gate — any
  178. `request -> bool` callable or an object with an `approve` method:
  179. ```python
  180. agent = Agent(
  181. capabilities=[find_orders, refund_order],
  182. approve=lambda request: request.bulk_count is None, # e.g. auto-deny bulk writes
  183. )
  184. ```
  185. Anything touching **more than one row** needs an explicit confirm at every
  186. autonomy level — even for agents trusted to write freely (`confirm_bulk=True`
  187. by default).
  188. ## Identity, row-level security, and the audit trail
  189. Tell the agent who it's acting for, and every capability knows it — your existing
  190. per-user logic keeps working, and one user's agent can never see another's rows:
  191. ```python
  192. from reins import Agent, Context, capability
  193. @capability(reads=True, scope="user")
  194. def list_my_orders(ctx: Context) -> list[dict]:
  195. """List the calling user's orders."""
  196. return store.orders(user=ctx.principal) # scoped to the caller — RLS
  197. agent = Agent(capabilities=[list_my_orders], principal="user:alice")
  198. agent.ask("what did I order last week?") # ctx.principal == "user:alice"
  199. agent.ask("…", principal="user:bob") # per-call override (e.g. per request)
  200. ```
  201. A `scope`-annotated capability **refuses to run** if no principal is set — fail
  202. closed, with a message telling you what to pass. And every write attempt — refused,
  203. denied, approved, or executed — lands in a structured, PII-redacted audit trail:
  204. ```python
  205. for r in agent.audit.records:
  206. print(r.timestamp, r.principal, r.decision, r.capability, r.arguments)
  207. # 2026-07-03 … user:alice approved update_password {'user_id': 7, 'password': '[redacted]'}
  208. # 2026-07-03 … user:alice executed update_password {'user_id': 7, 'password': '[redacted]'}
  209. ```
  210. Plug in your own sink with `Agent(audit=...)` — if a write can't be audited, it
  211. doesn't run.
  212. ## Code-mode: perfect work, near-zero tokens
  213. For anything beyond a trivial call, the agent doesn't ping-pong data through the
  214. model — it **writes a short program** that runs in a sandbox, calls your
  215. capabilities as plain functions, and prints back only the answer:
  216. ```python
  217. # what the model writes (and you can inspect):
  218. overdue = find_orders(status="overdue")
  219. print(f"{len(overdue)} overdue orders, {sum(r['total'] for r in overdue)} owed")
  220. ```
  221. A thousand rows flow from your function into the sandbox, get aggregated there,
  222. and a **single line** returns to the model. Crucially, the sandbox isolates
  223. computation, **never authority**: every call a program makes passes the same
  224. policy → approval → audit → row-level-security chain as a direct call — a
  225. gated write pauses at your terminal even mid-program.
  226. The default sandbox is a whitelisted-import subprocess (great for development;
  227. honestly labeled: not a hard security boundary). For production:
  228. ```python
  229. from reins import Agent, DockerSandbox
  230. agent = Agent(capabilities=[...], sandbox=DockerSandbox()) # no network, read-only
  231. agent = Agent(capabilities=[...], mode="simple") # or: no programs at all
  232. ```
  233. ## Drop it into your web app
  234. Add a chat endpoint to the app your users already log in to — and let their
  235. existing session decide what each of them can see:
  236. ```python
  237. from reins import Agent, endpoint
  238. agent = Agent.from_orm(db, models=[Order, Invoice])
  239. # a WSGI app: POST /ask runs read-only; identity comes from the live session
  240. app.wsgi_app = endpoint( # Flask; FastAPI via WSGIMiddleware
  241. agent,
  242. identity=lambda req: req.cookies.get("user_id"), # your auth, reused
  243. )
  244. ```
  245. `endpoint()` is read-only by default (no write route exists at all). The
  246. `identity` you pass flows straight into row-level security, so one user's chat can
  247. never surface another's rows — no second auth system. There are native
  248. `reins.web.flask_blueprint(agent)` and `reins.web.fastapi_router(agent)` too.
  249. Drop the chat box on any page — one self-contained element, no build step:
  250. ```python
  251. from reins import chat_widget
  252. page_html += chat_widget("/ask") # renders <reins-chat>, POSTs with your cookies
  253. ```
  254. ## Scale without paying for it
  255. Registered 10 capabilities or 10,000? The model's base context is **byte-identical**:
  256. above a small threshold, Reins shows the model one `search_capabilities` tool instead
  257. of every schema — it discovers just the operations it needs, which then become
  258. directly callable. Attach a schema index and your data model works the same way:
  259. ```python
  260. from reins import Agent, SchemaIndex, TableInfo
  261. agent = Agent(
  262. capabilities=every_operation_in_your_app, # hundreds? fine.
  263. schema=SchemaIndex(tables=(
  264. TableInfo("orders", "Customer orders.", ("id", "status", "total")),
  265. TableInfo("refunds", "Issued refunds.", ("id", "order_id", "amount")),
  266. )),
  267. )
  268. agent.ask("how many refunds this week?")
  269. # model: search_capabilities("refunds") → finds find_refunds → calls it. ~700 chars
  270. # of base context — the same whether you registered 20 operations or 20,000.
  271. ```
  272. `Agent.from_orm(...)` builds both the capabilities and this schema index from your
  273. models automatically, so scale is free out of the box.
  274. ## Never a black box
  275. Ask what the agent just did and get a straight answer — the operations it found,
  276. the code it wrote, every call and its result, each approval decision:
  277. ```python
  278. agent.run("cancel order ORD-2")
  279. print(agent.explain())
  280. # ── reins trace ──
  281. # outcome: executed · turns: 2
  282. # ⚠ approval: update_order: approved (approval_required)
  283. # • call: update_order(ref='ORD-2', status='cancelled')
  284. # answer: Order ORD-2 has been cancelled.
  285. ```
  286. `reins ask <db-url> "…" --trace` prints the same. Arguments are PII-redacted in
  287. the trace, just like the audit log.
  288. ## Reins vs. graph frameworks
  289. | Aspect | Graph frameworks (LangChain / LangGraph) | Reins |
  290. | ------------------- | ---------------------------------------- | ------------------------------------------------ |
  291. | Mental model | You draw a graph of nodes and edges | You expose functions; the agent finds the path |
  292. | Control flow | Predefined by you | Decided by the model, within your guardrails |
  293. | Adding it to an app | Wrap logic in framework primitives | Decorate functions you already have |
  294. | CRUD on a database | Often raw SQL tools, or custom nodes | Calls your typed methods, inheriting your auth |
  295. | Debuggability | Debug the framework's internals | Debug your own small loop and your own functions |
  296. | Languages | Python-first | Python, Go, and TypeScript — one shared conformance suite |
  297. ## Status
  298. Reins is at its first **Python alpha** (`0.1.0a1`). Everything below works today:
  299. typed capabilities derived from your functions or ORM, the `ask()` / `run()` safety
  300. boundary, deterministic write policy with the autonomy ladder, the human approval
  301. gate with previews and bulk confirm, a structured audit trail, identity propagation
  302. with row-level scoping, code-mode in a sandbox, on-demand discovery, budgets, the
  303. zero-code CLI, instant web integration, and seven model providers behind one
  304. interface — all under a coverage-gated, `mypy --strict` build. APIs may change
  305. before `1.0`.
  306. ### Roadmap
  307. - [x] Typed capabilities from your functions — schema and read/write classification
  308. - [x] The agent loop with `ask()` / `run()` and a strict read-only boundary
  309. - [x] Deterministic write policy and the autonomy ladder
  310. - [x] Human approval gate — previews, `[y]/[n]/[s]how`, pluggable `approve=`, bulk confirm
  311. - [x] Structured audit log, identity propagation, and row-level scoping
  312. - [x] Any model: Anthropic, OpenAI, Gemini, Groq, Z.ai/GLM, Ollama, vLLM
  313. - [x] On-demand capability & schema discovery — constant context at any scale
  314. - [x] Code-mode execution — sandboxed programs, data never transits the model
  315. - [x] Budgets (turns/tokens/cost/time) and history compaction that keeps the goal
  316. - [x] Record / replay — `RecordingModel` / `ReplayModel` capture a run and re-run it offline, deterministically
  317. - [x] SQLAlchemy **and Django** auto-exposure — `Agent.from_orm(...)`, zero capabilities
  318. - [x] Zero-code CLI — `reins chat` / `ask` / `inspect <db-url>` and `from_module`
  319. - [x] Instant web integration — `reins.endpoint`, `<reins-chat>`, session-identity → RLS
  320. - [x] A flagship end-to-end example (FastAPI + SQLAlchemy, gated writes) — `make demo`
  321. - [x] **Go package** (`packages/go`) — same verbs, passes the shared conformance suite; capabilities + classification + linter, the `Ask`/`Run` loop, full safety (policy/approval/audit/RLS), progressive disclosure, an OpenAI-compatible adapter for all providers above, GORM `FromORM`, and a `reins inspect|ask|chat <db-url>` CLI. Remaining: a native Go code-mode sandbox.
  322. - [x] **TypeScript package** (`packages/js`) — same verbs, **passes the shared conformance suite**; the core types + `Model`/`FakeModel`, capabilities + classification + linter, the async `ask`/`run` loop, full safety (policy/approval/audit/RLS), dual progressive disclosure, an OpenAI-compatible adapter for all providers above, `fromDrizzle` (auto-expose Drizzle models via the optional `reins/orm` subpath), a `reins inspect|ask|chat <db-url>` CLI (zero-dep SQLite reflection via `node:sqlite`), and code-mode (a `WorkerSandbox` dev tier — bridged calls gated like direct ones). Remaining: `<reins-chat>`.
  323. ## Development
  324. ```bash
  325. make setup # create a local venv, install the package and dev tools, set up pre-commit
  326. make check # the gate: ruff + mypy --strict + tests + conformance
  327. ```
  328. The Python package lives in `packages/python`. See [CONTRIBUTING.md](CONTRIBUTING.md) for
  329. the workflow and conventions.
  330. ## Go
  331. The Go package (`packages/go`, module `github.com/shamspias/reins/packages/go`) mirrors
  332. the Python verbs and passes the same conformance suite. The zero-code CLI works the same
  333. way — point it at a SQLite database and it reflects the schema into intent-level
  334. capabilities (no models to write):
  335. ```bash
  336. go install github.com/shamspias/reins/packages/go/cmd/reins@latest
  337. reins inspect ./app.db # list the capabilities Reins would expose (no key needed)
  338. reins ask ./app.db "how many active customers?" # read-only answer
  339. reins chat ./app.db --model groq:llama-3.3-70b-versatile
  340. ```
  341. `ask` and `chat` are **read-only** (writes aren't even generated); `inspect --write` reveals
  342. the gated create/update/delete. The model is resolved from `--model` (`provider:model`) or the
  343. environment — the same seven providers as Python. In code:
  344. ```go
  345. model, _ := reins.ResolveModel("openai:gpt-4o") // or reins.DefaultModel() from env
  346. // The input schema is reflected from RefundArgs; access is classified from the name.
  347. refund := reins.Define[RefundArgs]("refund_order", "Refund an order by its id.",
  348. func(ctx reins.Context, args map[string]any) (any, error) {
  349. return refundOrder(args["order_id"])
  350. })
  351. agent, _ := reins.NewAgent(model, reins.WithCapabilities(refund))
  352. res, _ := agent.Ask("how much did order 8842 cost?") // Ask never writes; Run gates writes
  353. fmt.Println(res.Output.Text)
  354. ```
  355. Run `make go-check` for the Go gate (gofmt + vet + tests). A native Go code-mode sandbox is
  356. the one remaining piece.
  357. ## Documentation
  358. - **[QUICKSTART.md](QUICKSTART.md)** — the adoption ladder, rung by rung, all runnable.
  359. - **[EXTENDING.md](EXTENDING.md)** — swap in your own model, policy, approval gate,
  360. sandbox, or audit sink.
  361. - **[`examples/fastapi_sqlalchemy/`](examples/fastapi_sqlalchemy/)** — a complete app
  362. (`make demo`, and a real FastAPI server).
  363. - **[SECURITY.md](SECURITY.md)** — the threat model and a production deployment checklist.
  364. ## License
  365. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.