{"id":51325796,"url":"https://github.com/shamspias/reins","last_synced_at":"2026-07-01T18:03:24.645Z","repository":{"id":162225365,"uuid":"625567062","full_name":"shamspias/reins","owner":"shamspias","description":"A lightweight agent harness you bolt onto your app so an LLM can operate it — safely, and cheaply.","archived":false,"fork":false,"pushed_at":"2026-06-29T07:16:49.000Z","size":1428,"stargazers_count":90,"open_issues_count":0,"forks_count":15,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-06-29T09:13:24.283Z","etag":null,"topics":["agent-framework","agent-harness","agent-memory","agent-orchestration","agent-skills","agentic-ai","agentic-workflow","harness","harness-engineering","harness-framework","reins"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shamspias.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-04-09T14:12:26.000Z","updated_at":"2026-06-29T07:18:14.000Z","dependencies_parsed_at":"2023-10-11T08:19:39.152Z","dependency_job_id":null,"html_url":"https://github.com/shamspias/reins","commit_stats":null,"previous_names":["shamspias/reins"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/shamspias/reins","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shamspias%2Freins","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shamspias%2Freins/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shamspias%2Freins/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shamspias%2Freins/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shamspias","download_url":"https://codeload.github.com/shamspias/reins/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shamspias%2Freins/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35017091,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["agent-framework","agent-harness","agent-memory","agent-orchestration","agent-skills","agentic-ai","agentic-workflow","harness","harness-engineering","harness-framework","reins"],"created_at":"2026-07-01T18:03:23.713Z","updated_at":"2026-07-01T18:03:24.639Z","avatar_url":"https://github.com/shamspias.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Reins\n\n**A lightweight agent harness you bolt onto your app so an LLM can operate it — safely and cheaply.**\n\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)\n[![Status](https://img.shields.io/badge/status-alpha-orange.svg)](#status)\n\nPoint Reins at functions you already have — or your ORM models — and hand it a goal in\nplain language. It works out which of your operations to call and in what order, runs\nthem **through your own code (never raw SQL by default)**, and returns the result, with\nnear-zero token overhead and safe-by-default writes. There is no graph to draw: you\nexpose your app, and the agent operates it.\n\n\u003e **The wedge: Reins gives the model your _verbs_, not your _tables_.**\n\u003e Intent-named functions like `refund_order` carry the meaning that raw schemas and\n\u003e OpenAPI specs strip away — which is exactly where text-to-SQL and auto-generated tool\n\u003e layers lose their reliability.\n\n## Example\n\n```python\nfrom reins import Agent, capability\n\n@capability\ndef find_orders(status: str) -\u003e list[dict]:\n    \"\"\"Find orders by their current status.\"\"\"\n    return store.orders(status=status)          # your existing code\n\n@capability\ndef refund_order(order_id: int) -\u003e dict:\n    \"\"\"Refund a customer's order by its public order number.\"\"\"\n    return payments.refund(order_id)            # your existing code\n\nagent = Agent(capabilities=[find_orders, refund_order])\n\n# ask() is read-only: it can never call a write capability.\nresult = agent.ask(\"how many orders are stuck in processing?\")\nprint(result.output.text)\n\n# run() may write: writes are gated before they execute.\nagent.run(\"refund order 8842\")\n```\n\nThe model is read from your environment (`ANTHROPIC_API_KEY`), or pass one explicitly\nwith `Agent(model=\"anthropic:claude-...\")`.\n\n## Why Reins\n\n- **Your verbs, not your tables.** The model sees intent-named operations with real\n  descriptions and types — not opaque columns or hand-written JSON schemas.\n- **Safe by default.** `ask()` is read-only and can never write; writes are opt-in and\n  gated. Beginners cannot cause damage, and the boundary is enforced in code, not in a\n  prompt the model can reason around.\n- **You hold the reins.** Reins runs *your* functions, so it inherits your existing\n  validation, authorization, and business rules. No raw SQL against your database.\n- **Tiny and transparent.** The core is a small, readable loop you own — no hidden\n  graph, no framework internals to reverse-engineer when you hit a ceiling.\n- **Provider-agnostic.** Bring any model through a thin adapter; Anthropic ships in the\n  box.\n\n## How it works\n\n1. **Register.** Decorate the functions you want to expose. Reins reads their type hints\n   and docstrings to derive a schema and classify each as read or write.\n2. **Discover.** The agent is shown your intent-named operations and the goal.\n3. **Plan.** It decides which operations to call, and in what order, to reach the goal.\n4. **Govern.** Reads run freely; writes pass through policy, approval, and audit before\n   anything touches your data.\n5. **Return.** Only results cross back to the model, and every decision and call is\n   traceable.\n\n## Installation\n\nReins requires **Python 3.11+**.\n\n```bash\npip install reins                 # core (first PyPI release coming soon)\npip install \"reins[anthropic]\"    # with the Anthropic model backend\n```\n\nUntil the first published release, install from source:\n\n```bash\ngit clone https://github.com/shamspias/reins\npip install -e \"reins/packages/python[anthropic]\"\nexport ANTHROPIC_API_KEY=sk-...\n```\n\n## The two verbs\n\nReins has exactly two entry points, and they *are* the safety model:\n\n- **`ask(goal)`** — the agent may only read. It never writes, never blocks, and never\n  prompts. Use it for dashboards, search, analytics, and \"what is…\".\n- **`run(goal)`** — the agent may read and write. Writes are detected automatically and\n  gated for approval. Use it for \"do something\": create, update, refund, send.\n\nRead/write classification is automatic and errs toward \"write\" when a name is ambiguous,\nso a wrong guess only ever adds a needless approval — it can never let a write slip\nthrough as a read. Override it explicitly when you know better:\n\n```python\n@capability(reads=True)\ndef export_report(month: str) -\u003e bytes: ...\n\n@capability(destructive=True, confirm=True)\ndef deactivate_user(user_id: int) -\u003e None: ...\n```\n\n## Reins vs. graph frameworks\n\n| Aspect              | Graph frameworks (LangChain / LangGraph) | Reins                                            |\n| ------------------- | ---------------------------------------- | ------------------------------------------------ |\n| Mental model        | You draw a graph of nodes and edges      | You expose functions; the agent finds the path   |\n| Control flow        | Predefined by you                        | Decided by the model, within your guardrails     |\n| Adding it to an app | Wrap logic in framework primitives       | Decorate functions you already have              |\n| CRUD on a database  | Often raw SQL tools, or custom nodes     | Calls your typed methods, inheriting your auth   |\n| Debuggability       | Debug the framework's internals          | Debug your own small loop and your own functions |\n| Languages           | Python-first                             | Python today; Go and TypeScript planned          |\n\n## Status\n\nReins is in **early development**, Python first. The core works today: typed capabilities\nderived from your functions, the agent loop, the `ask()` / `run()` safety boundary, and\npluggable model backends. APIs may change before `1.0`.\n\n### Roadmap\n\n- [x] Typed capabilities from your functions — schema and read/write classification\n- [x] The agent loop with `ask()` / `run()` and a strict read-only boundary\n- [x] Provider-agnostic model backends (Anthropic included)\n- [ ] Policy, human approval, and audit for writes\n- [ ] ORM auto-exposure (SQLAlchemy, Django) and a zero-code `reins chat \u003cdb-url\u003e`\n- [ ] Code-mode execution and on-demand capability/schema discovery\n- [ ] Row-level security and identity propagation\n- [ ] Go and TypeScript packages, verified against one shared conformance suite\n\n## Development\n\n```bash\nmake setup     # create a local venv, install the package and dev tools, set up pre-commit\nmake check     # the gate: ruff + mypy --strict + tests + conformance\n```\n\nThe Python package lives in `packages/python`. See [CONTRIBUTING.md](CONTRIBUTING.md) for\nthe workflow and conventions.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshamspias%2Freins","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshamspias%2Freins","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshamspias%2Freins/lists"}