Metadata-Version: 2.4
Name: quinny
Version: 0.1.0
Summary: A task-oriented intent language for AI coding agents.
Author: Weijia Huang
License: Apache-2.0
Project-URL: Homepage, https://github.com/Xavierhuang/quinny
Project-URL: Repository, https://github.com/Xavierhuang/quinny
Project-URL: Documentation, https://github.com/Xavierhuang/quinny/blob/main/docs/LANGUAGE_SPEC.md
Project-URL: Issues, https://github.com/Xavierhuang/quinny/issues
Keywords: ai,codegen,intent-language,dsl,llm,planning,agents
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lark>=1.1.9
Requires-Dist: networkx>=3.0
Requires-Dist: rich>=13.0
Requires-Dist: anthropic>=0.90.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Dynamic: license-file

# Quinny

**A task-oriented intent language for AI coding agents.**

Quinny sits *above* Python, Swift, TypeScript, Rust, etc. You describe **what**
should be built — goals, inputs/outputs, dependencies, constraints, and how to
verify it — and Quinny compiles that into a validated **task graph**, then drives
an LLM to generate, verify, and assemble the actual code.

```
English  →  Quinny (.qn)  →  Task Graph  →  Plan  →  Generated code (Python, …)
             │                  │            │          │
             │ 10 keywords      │ DAG +      │ layers    │ per-node LLM gen
             │ indentation      │ validation │           │ + verify + repair
```

A `.qn` file is **not code that runs** — it is a structured, human-readable,
version-controllable description of intent. `quinny check` catches missing
components and broken dependencies *at plan time* (cheap), before a single line
of code is generated.

---

## Install

```bash
# One-liner — installs the Python-free binary on Apple Silicon, else falls back to pip:
curl -fsSL https://raw.githubusercontent.com/Xavierhuang/quinny/main/install.sh | sh

# Or straight from PyPI (needs Python 3.10+):
pip install quinny
```

The installer honors `QUINNY_METHOD=pip|binary`, `QUINNY_VERSION=vX.Y.Z`, and
`QUINNY_PREFIX=<dir>`. Prebuilt binaries are attached to each
[GitHub Release](https://github.com/Xavierhuang/quinny/releases).

From source:

```bash
git clone https://github.com/Xavierhuang/quinny
cd quinny
pip install -e .
```

Requires Python 3.10+.

## Quickstart

Write `hello.qn`:

```
project SimpleLogin

task Login
    goal
        Authenticate a user with email and password.
    input
        email
        password
    output
        jwt_token
    constraint
        Under 200ms latency.
    test
        Invalid password is rejected.
    success
        Valid credentials produce a token.
```

Validate and inspect the plan (no LLM, no key needed):

```bash
quinny check hello.qn      # ✓ parses + graph is valid
quinny plan  hello.qn      # execution layers
quinny graph hello.qn      # the task graph
```

Generate code (needs credentials — see below):

```bash
quinny build hello.qn --full-verify --assemble -o out/
# → out/login.py, out/shared_types.py, out/main.py, requirements.txt, README.md
```

## The CLI

| Command | What it does | Needs an LLM? |
|---|---|---|
| `quinny parse <file>`  | Parse a `.qn` to its AST | no |
| `quinny check <file>`  | Parse + validate the task graph (missing deps, cycles) | no |
| `quinny graph <file>`  | Print the task graph | no |
| `quinny plan  <file>`  | Show execution layers (what can run in parallel) | no |
| `quinny gen "<english>"` | Translate English → a `.qn` plan | **yes** |
| `quinny build <file>`  | Generate code from a `.qn` (per-node gen → verify → repair → assemble) | **yes** |

`quinny build` flags: `--target python`, `-o <dir>`, `--full-verify`, `--assemble`,
`--model <m>` (and per-stage `--types-model` / `--node-model` / `--repair-model` /
`--assemble-model`), `--max-repair N`, `--only <node>`.

## Credentials

`gen` and `build` call an LLM. Quinny uses the Anthropic Python SDK, so it reads
standard environment variables:

- **Anthropic API key:** `export ANTHROPIC_API_KEY=sk-...`
- **Any Anthropic-compatible proxy** (bring-your-own gateway): set
  `ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN` (Bearer). `QUINNY_MODEL` sets the
  default model. Everything before `gen`/`build` (`parse`/`check`/`graph`/`plan`)
  needs **no** credentials.

## The language

Ten keywords, indentation-sensitive, no loops or variables — those belong to the
target language the agent emits:

```
project    task       component
goal       input      output
constraint depends    uses
test       success
```

Full reference: **[docs/LANGUAGE_SPEC.md](docs/LANGUAGE_SPEC.md)**.
Writing plans with an LLM: **[docs/AI_PROMPT.md](docs/AI_PROMPT.md)**.
First-time walkthrough: **[docs/getting-started.md](docs/getting-started.md)**.

## Using it with Claude Code

Quinny is a CLI, so [Claude Code](https://claude.com/claude-code) can use it the
moment it's installed — just ask it to *"use `quinny` to plan and build …"*. For a
`/quinny` slash command and a paste-in `CLAUDE.md` block that teaches Claude when
to reach for it, see **[docs/claude-code.md](docs/claude-code.md)**.

## When to use Quinny (honest scope)

Quinny is **v0.1 / alpha**, and it is not free — a `build` makes many sequential
LLM calls, so it costs **more** tokens and time than a single "just write it"
prompt. It earns that cost only on **genuinely complex, multi-component projects**
where a one-shot attempt would miss a piece, leave a dependency dangling, or drift
between files — the kind of failure that's expensive to debug afterward.

- **Reach for Quinny:** larger systems with several interdependent components,
  cross-file contracts, and non-trivial ordering; when you want the plan reviewed
  before code is written; when you want each file verified as it's generated.
- **Don't bother:** simple scripts, one-file utilities, single features, quick
  edits, refactors, bug fixes — a plain prompt is faster, cheaper, and just as
  reliable.

The `.qn` plan is the durable artifact: readable, editable, diffable, reusable.

## Status

Implemented: parser, task-graph builder + validator, planner, code generator,
verify/repair loop, `main.py` assembly, CLI.

Roadmap: a JSON/schema plan format (for dependency-free tooling), parallel node
execution, and code-gen targets beyond Python.

## Contributing

Issues and PRs welcome. Please keep the language small (the v0.1 surface is 10
keywords on purpose) and add a test for any parser/graph/validator change.

## License

[Apache-2.0](LICENSE).
