Metadata-Version: 2.4
Name: newt-agent-py
Version: 0.7.3
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: pytest>=7 ; extra == 'test'
Requires-Dist: pytest-asyncio>=0.21 ; extra == 'test'
Provides-Extra: test
License-File: LICENSE
Summary: Python bindings for newt-agent — agentic coder runtime (newt-core, newt-tools, newt-coder, newt-eval, newt-inference, newt-acp-worker, newt-mcp-server submodules)
Keywords: newt,agentic,coder,llm,ollama,vllm,mcp,acp
Home-Page: https://github.com/hartsock/newt-agent
Author-email: Shawn Hartsock <hartsock@users.noreply.github.com>
License: Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/Gilamonster-Foundation/newt-agent
Project-URL: Repository, https://github.com/Gilamonster-Foundation/newt-agent

# Newt-Agent

<p align="center">
  <img src="docs/logos/newt-agent-logo_source.png" alt="Newt-Agent logo" width="256" />
</p>

> Small, fast, local-first agentic coder.
> **vi to Hermes-Agent's emacs.**

A single Rust binary with a sharp, minimal tool set. It runs against your
local hardware by default — no cloud bytes leave your machine unless you
deliberately install a provider plugin. Opinionated, not extensible.

## Why — the bridle, not just the harness

An agent *harness* helps the model do work; a **bridle** lets the operator
*steer* — and prove, after the fact, exactly where the horse went. Newt is an
experiment in making Object Capability (OCAP) security — long considered
theoretically correct but practically unimplementable — pragmatic inside an
agent loop, as a reusable concept
([`agent-bridle`](https://github.com/Gilamonster-Foundation/agent-bridle))
intended to be pluggable into other harnesses, not just this one.

OCAP's algebraic construction means some questions are answered
*structurally*, not by audit-log archaeology:

- Who acted on what, and when?
- Who granted the authority for this to do that?
- Did what they permitted actually happen — and did **only** what they
  permitted happen?

For anyone whose work lives on provenance, authority, integrity, and data
sovereignty — lawyers, clinicians, data scientists — those answers have to be
properties of the system, not promises in a policy document.

If it doesn't find its day in the sun, it was fun anyway.

## Quick start

```bash
git clone https://github.com/Gilamonster-Foundation/newt-agent
cd newt-agent
just install          # release binaries → ~/bin/newt, ~/bin/newt-mcp-server
newt code             # TUI coder in the current directory
```

Run `newt --help` for every mode (worker, MCP server, doctor, config, …) —
the binary is the authority on its own surface, this file is not. Python
bindings live in [`newt-agent-py/`](./newt-agent-py/) (`pip install
newt-agent-py`, import path `newt_agent`).

## Design laws

The invariants. Each links to the decision record that argues it.

- **Local-first inference.** The default binary speaks only to local
  backends. Cloud providers are opt-in subprocess plugins speaking the
  JSON-RPC schema in [`plugins-protocol/`](./plugins-protocol/) — the opt-in
  is enforced at the **build** level, not a runtime flag.
- **Fail-closed OCAP.** Authority is a caveat lattice, not a denylist; a
  fixed safety floor no mode or grant can unlock. See
  [`docs/decisions/agentic_object_capability_security.md`](./docs/decisions/agentic_object_capability_security.md)
  and [`docs/decisions/ocap_confinement_model.md`](./docs/decisions/ocap_confinement_model.md).
- **Small crates, zero warnings, coverage-gated.** `just check` mirrors CI;
  the pre-push hook runs it. One operator's leverage *is* this discipline.
- **Patch, not prose.** Delegated work is verified by the harness (real
  diffs, real test runs — [`newt-eval/`](./newt-eval/)), never by trusting a
  model's summary of itself.
- **Skills are on-demand context.** The prompt carries an index; bodies load
  when used. See [`docs/decisions/agent-skills.md`](./docs/decisions/agent-skills.md)
  and the bundled skills in [`.newt/bundled-skills/`](./.newt/bundled-skills/).
- **Issues are ground truth.** [`ROADMAP.md`](./ROADMAP.md) sequences
  delivery, but GitHub issue state is authoritative — the document is only
  the map.
- **Causal ordering, not wall-clock.** Timestamps are display *claims*; the
  conversation store orders on signed per-writer ticks + content hashes. See
  [`docs/decisions/conversation_context_architecture.md`](./docs/decisions/conversation_context_architecture.md).

## Field notes

The durable output of this experiment is what building it teaches about how
LLMs behave inside a harness:

- **[Summarization-induced hallucination](./docs/notes/2026-06-13-summarization-induced-hallucination.md)**
  — context compression that *summarizes* a session can make the model
  hallucinate APIs it had already read. A confident summary is worse than a
  labelled absence: absence routes the model to re-read; a summary suppresses
  recovery.
- **[Truncation honesty](./docs/testing/results/context-baseline-f0f4f6e.md)**
  — silent context truncation yields *silently wrong* answers; every fix
  moves the failure, it doesn't always remove it.
- **[Coder-driving sweet spots](./docs/notes/2026-05-31-newt-coder-driving-sweet-spots.md)**
  — where small local models are and aren't reliable at agentic coding.
- **[Hermes learnings](./docs/design/context-memory-hermes-learnings.md)**
  — take the algorithms, refuse the architecture.

## Where things live

| What | Where |
|---|---|
| Forward plan | [`ROADMAP.md`](./ROADMAP.md) (issue numbers are the live state) |
| Release history | [`CHANGELOG.md`](./CHANGELOG.md) |
| Design docs & studies | [`docs/design/`](./docs/design/) |
| Decision records | [`docs/decisions/`](./docs/decisions/) |
| Evaluation harness | [`newt-eval/README.md`](./newt-eval/README.md) |
| Local gate | `just check` (see [`justfile`](./justfile)) |

## License

Apache-2.0. See [LICENSE](./LICENSE).

