Metadata-Version: 2.4
Name: newb
Version: 0.5.0
Summary: Test your package through the eyes of a newbie agent — a fresh AI agent reads only your docs/skills and tries to use your package.
Author-email: Yusuke Watanabe <ywata1989@gmail.com>
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://github.com/ywatanabe1989/newb
Project-URL: Repository, https://github.com/ywatanabe1989/newb
Keywords: agentic-test,newbie-test,skill-verify,documentation-testing,ai-agent,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Provides-Extra: yaml
Requires-Dist: PyYAML>=6.0; extra == "yaml"
Dynamic: license-file

# newb

<p align="center"><img src="./assets/newb-logo.png" width="220" alt="newb mascot"/></p>

A fresh AI agent reads only your docs and tries to use your package. If it
succeeds, your docs work.

## Install

```bash
pip install newb
```

## Use

```bash
newb ./docs                                     # any dir of .md files
newb https://github.com/user/repo.git           # git URL — auto-clones
newb ./docs --format markdown >> README.md
newb ./docs --runtime local --auth claude-code  # host subprocess
```

Asks a fresh Claude agent four canonical questions (what for / problems
solved / quick start / when not to use), plus any author-defined tests in
`tests_newb.yaml`. Output: JSON (for CI) or markdown.

### Author tests (`tests_newb.yaml`)

```yaml
- name: redirects_parallel
  prompt: How do I run things in parallel?
  expect_contains: ["does not"]
  judge: "Must redirect to an alternative tool, not hallucinate."
```

Each test combines optional substring grading and an optional LLM judge.

## Runtime · Auth

| `--runtime` | what                                          |
|-------------|-----------------------------------------------|
| `docker`    | default — clean container, no host leakage    |
| `local`     | host subprocess with isolated `HOME`          |
| `apptainer` | HPC (planned)                                 |

| `--auth`      | what                                          |
|---------------|-----------------------------------------------|
| `api-key`     | default — uses `$ANTHROPIC_API_KEY`           |
| `claude-code` | copies host `~/.claude/.credentials*`         |

## Library

```python
import newb
report = newb("./docs")
print(newb.render_markdown(report))
```

## Requirements

- `docker` on PATH (or `claude` CLI if `--runtime local`)
- `$ANTHROPIC_API_KEY` (or `--auth claude-code`)
- Python 3.10+

## License

AGPL-3.0-only.
