@aeye/ginny 0.3.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +674 -0
- package/README.md +330 -0
- package/aeye-ginny-api.md +193 -0
- package/aeye-ginny-architecture.md +180 -0
- package/aeye-ginny-cli.md +186 -0
- package/aeye-ginny.md +109 -0
- package/dist/index.js +440025 -0
- package/package.json +76 -0
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
# @aeye/ginny — Architecture: Sub-Agents & the Build Loop
|
|
2
|
+
|
|
3
|
+
Part of the [@aeye/ginny LLM reference](./aeye-ginny.md).
|
|
4
|
+
|
|
5
|
+
## The pipeline
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
┌─────────────┐
|
|
9
|
+
user request ──▶ │ programmer │
|
|
10
|
+
└──────┬──────┘
|
|
11
|
+
┌────────────────┬──────┴──────┬────────────────┐
|
|
12
|
+
▼ ▼ ▼ ▼
|
|
13
|
+
┌─────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
|
14
|
+
│ architect │ │ designer │ │ dba │ │ researcher │
|
|
15
|
+
│ (types) │ │ (fns) │ │ (vars) │ │ (web) │
|
|
16
|
+
└─────────────┘ └──────┬───────┘ └──────────────┘ └──────────────┘
|
|
17
|
+
│
|
|
18
|
+
▼ (recursive spin-up)
|
|
19
|
+
programmer
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
The CLI entry (`src/index.ts`) appends the user's text to a `Message[]`
|
|
23
|
+
history and streams the **programmer** prompt (`programmer.get('stream',
|
|
24
|
+
…)`). Each `message` event is captured into history so the next REPL turn
|
|
25
|
+
has full context. A shared `originalRequest` and a `programmerDepth`
|
|
26
|
+
(starting at 0) are threaded down through every recursive sub-agent.
|
|
27
|
+
|
|
28
|
+
Each sub-agent is an `ai.prompt(...)` (from `@aeye/core` via the
|
|
29
|
+
`@aeye/ai` instance in `src/ai.ts`) with its own tool list. Sub-agents
|
|
30
|
+
other than the programmer set `excludeMessages: true` — they take their
|
|
31
|
+
task through a `{{description}}` / `{{question}}` template variable rather
|
|
32
|
+
than inheriting the parent's conversation, which avoids forwarding a
|
|
33
|
+
half-finished `tool_calls` assistant message to the provider.
|
|
34
|
+
|
|
35
|
+
## The five sub-agents and their tools
|
|
36
|
+
|
|
37
|
+
All tool names below are the literal `name` fields the model sees.
|
|
38
|
+
|
|
39
|
+
### programmer (`gin_programmer`)
|
|
40
|
+
|
|
41
|
+
The orchestrator. Writes, tests, and finalizes gin programs; delegates to
|
|
42
|
+
the others when it needs catalog items. `dynamic: true`,
|
|
43
|
+
`toolIterations` from `GIN_TOOL_ITERATIONS`. Tools:
|
|
44
|
+
|
|
45
|
+
- `find_or_create_types` → delegates to **architect**
|
|
46
|
+
- `find_or_create_functions` → delegates to **designer**
|
|
47
|
+
- `find_or_create_vars` → delegates to **dba**
|
|
48
|
+
- `research` → delegates to **researcher** (only present when Tavily is configured)
|
|
49
|
+
- `write`, `test`, `finish` — the build loop (below)
|
|
50
|
+
- `edit_type` — backwards-compatible edit of a saved type
|
|
51
|
+
- `search_fns`, `search_vars`, `print_fn` — inspect the catalog (lookups also register a saved fn into the engine so it becomes callable)
|
|
52
|
+
- `ask` — prompt the human user
|
|
53
|
+
|
|
54
|
+
The programmer's system prompt embeds: the full method surface of every
|
|
55
|
+
registered type, a names-only preview of the on-disk catalog, and the
|
|
56
|
+
signatures of fns already loaded this session. It distinguishes three
|
|
57
|
+
response modes — informational answers, simple one-shot computations
|
|
58
|
+
(straight to write/test/finish), and complex requests (a
|
|
59
|
+
**plan-and-approve** workflow: ask clarifying questions, present a written
|
|
60
|
+
plan of types/fns/vars, iterate until the user approves, then implement).
|
|
61
|
+
|
|
62
|
+
### architect (types)
|
|
63
|
+
|
|
64
|
+
Designs or picks gin types. Tools: `search_types`, `get_type`, `ask`.
|
|
65
|
+
Returns structured `{ use: string[], create: TypeDef[] }`.
|
|
66
|
+
|
|
67
|
+
### designer (functions)
|
|
68
|
+
|
|
69
|
+
Finds or authors reusable functions. Tools: `search_fns`, `get_fn`,
|
|
70
|
+
`print_fn`, `create_new_fn`, `edit_fn`, `ask`. Returns structured
|
|
71
|
+
`{ use: string[], created: string[] }`, and **validates** that every named
|
|
72
|
+
fn is actually readable on disk (re-prompts the model if it hallucinates).
|
|
73
|
+
|
|
74
|
+
- `create_new_fn` — the designer decides the signature (`args`, `returns`,
|
|
75
|
+
optional `types` aliases) and then **recursively spawns a programmer**
|
|
76
|
+
to author the body. Backwards behavior is enforced by the inner
|
|
77
|
+
programmer reaching a passing test and calling `finish({ saveAs })`.
|
|
78
|
+
- `edit_fn` — change a saved fn's signature + body. The new signature is
|
|
79
|
+
compat-checked **before** spawning the inner programmer: args may widen
|
|
80
|
+
(add optional params, widen types); returns may **narrow**. Removing
|
|
81
|
+
required args, narrowing arg types, or widening returns is rejected.
|
|
82
|
+
|
|
83
|
+
### dba (vars)
|
|
84
|
+
|
|
85
|
+
Curates `vars.*`. Tools: `search_vars`, `get_var`, `create_var`, `ask`.
|
|
86
|
+
For credentials/external parameters the user hasn't supplied, it creates
|
|
87
|
+
the var with a placeholder value and **setup instructions in the var's
|
|
88
|
+
`docs`** rather than halting to ask.
|
|
89
|
+
|
|
90
|
+
### researcher (web)
|
|
91
|
+
|
|
92
|
+
Only wired into the programmer when `ctx.features.webSearch` is true
|
|
93
|
+
(Tavily configured). Tools: `web_search` (Tavily; `query`, optional
|
|
94
|
+
`maxResults` default 5), `web_get_page` (`url`; renders HTML via headless
|
|
95
|
+
Puppeteer, parses PDF/DOCX/XLSX to markdown, output capped ~16k chars),
|
|
96
|
+
and `ask`. Returns structured `{ answer, sources }`.
|
|
97
|
+
|
|
98
|
+
## Recursion and the depth cap
|
|
99
|
+
|
|
100
|
+
Function authoring is recursive: programmer → `find_or_create_functions`
|
|
101
|
+
→ designer → `create_new_fn` → a fresh programmer that writes the body.
|
|
102
|
+
|
|
103
|
+
- `MAX_PROGRAMMER_DEPTH = 3` (in `src/context.ts`).
|
|
104
|
+
- `ctx.programmerDepth` increments by 1 on each `create_new_fn` /
|
|
105
|
+
`edit_fn`.
|
|
106
|
+
- `find_or_create_functions`, `create_new_fn`, and `edit_fn` set
|
|
107
|
+
`applicable` to require depth `< MAX_PROGRAMMER_DEPTH - 1`. The deepest
|
|
108
|
+
programmer **cannot** delegate further — it must write the function body
|
|
109
|
+
inline.
|
|
110
|
+
- When a programmer is authoring a specific fn body, `ctx.targetFn` is set
|
|
111
|
+
(the designer-designed signature). `find_or_create_functions` is
|
|
112
|
+
withheld in that case so the programmer can't respawn a designer for the
|
|
113
|
+
same task and recurse uncontrolled.
|
|
114
|
+
- A `programmerChain` records the ancestry so a deep programmer sees which
|
|
115
|
+
caller needs its output and what the original user request was.
|
|
116
|
+
|
|
117
|
+
## The write / test / finish loop
|
|
118
|
+
|
|
119
|
+
This is the programmer's core cycle (`src/tools/write.ts`, `test.ts`,
|
|
120
|
+
`finish.ts`):
|
|
121
|
+
|
|
122
|
+
1. **`write({ program: <ExprDef> })`** — stores the draft. It renders the
|
|
123
|
+
program back as TypeScript-like pseudocode (via `toCode`), runs static
|
|
124
|
+
validation, and reports:
|
|
125
|
+
- **ERRORS** (must be fixed before `test`),
|
|
126
|
+
- **WARNINGS** (advisory; too many block `finish`),
|
|
127
|
+
- a **complexity** figure vs the cap (continuous feedback so the model
|
|
128
|
+
decomposes before it's rejected).
|
|
129
|
+
Full problem detail (with underlined spans, in both TS and JSON form)
|
|
130
|
+
goes to `ginny.log` under a grep id; the tool result keeps the compact
|
|
131
|
+
TS form.
|
|
132
|
+
|
|
133
|
+
2. **`test({ args?, expectError? })`** — runs the draft. When a `targetFn`
|
|
134
|
+
is in scope the draft is wrapped in a lambda and invoked through gin's
|
|
135
|
+
call machinery (so `args` and `recurse` resolve like the saved fn
|
|
136
|
+
will); otherwise it runs via `engine.run`. `args` schema is auto-built
|
|
137
|
+
from the function's args type. Set `expectError: true` to treat a
|
|
138
|
+
runtime error as success (e.g. "divide by zero and tell me what
|
|
139
|
+
happens"). Var mutations from the run are persisted via dirty-tracking.
|
|
140
|
+
|
|
141
|
+
3. **`finish({ saveAs?, docs? })`** — finalize after a passing test.
|
|
142
|
+
- Without `saveAs`: returns the one-shot result; nothing is persisted.
|
|
143
|
+
- With `saveAs`: re-validates the draft and **rejects the save** if
|
|
144
|
+
warnings exceed `GIN_MAX_WARNINGS` (default 5), if any errors are
|
|
145
|
+
present, or if structural complexity exceeds `GIN_MAX_COMPLEXITY`
|
|
146
|
+
(default 400 — decompose into helper fns to reduce it; each helper
|
|
147
|
+
call costs 1 at the call site regardless of its body size). On
|
|
148
|
+
success it writes `./fns/<saveAs>.json` and registers the fn as a
|
|
149
|
+
callable top-level global.
|
|
150
|
+
|
|
151
|
+
"Everything is a function": there is no separate programs concept. A
|
|
152
|
+
finished one-shot computation is just a `fn() => T` whose `call.get` is
|
|
153
|
+
the program body.
|
|
154
|
+
|
|
155
|
+
## Catalog search behavior
|
|
156
|
+
|
|
157
|
+
`src/store.ts` implements search per directory. Important and easy to get
|
|
158
|
+
wrong: **search is keyword text-match scoring, not embeddings.**
|
|
159
|
+
|
|
160
|
+
- If a directory has at most `GIN_SEARCH_THRESHOLD` (default 20) entries,
|
|
161
|
+
**or** no keywords are given, search returns all entries (up to the
|
|
162
|
+
limit) with score 0.
|
|
163
|
+
- Above the threshold, each entry's searchable text (name, docs,
|
|
164
|
+
`extends`, prop names, etc.) is scored by counting keyword occurrences;
|
|
165
|
+
entries with score 0 are dropped; the top-N (default limit 10) are
|
|
166
|
+
returned.
|
|
167
|
+
|
|
168
|
+
The programmer's prompt also embeds a names-only preview (capped at 20 per
|
|
169
|
+
category with a `+N more` suffix) so the model can skip blind `search_*`
|
|
170
|
+
calls when an obviously-named entry already exists.
|
|
171
|
+
|
|
172
|
+
## Editing existing types
|
|
173
|
+
|
|
174
|
+
- `edit_type({ name, def })` (programmer tool) — replace a saved type's
|
|
175
|
+
definition. Allowed: add **optional** fields, widen existing field
|
|
176
|
+
types, loosen constraints. Rejected: remove fields, add required fields,
|
|
177
|
+
narrow field types, change the type class. The compat check runs at
|
|
178
|
+
parse time. If a change is genuinely breaking, the right move is to
|
|
179
|
+
create a new type/fn under a different name so existing callers keep
|
|
180
|
+
working.
|
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
# @aeye/ginny — CLI, Configuration & Persistence
|
|
2
|
+
|
|
3
|
+
Part of the [@aeye/ginny LLM reference](./aeye-ginny.md).
|
|
4
|
+
|
|
5
|
+
## Invocation
|
|
6
|
+
|
|
7
|
+
The binary is `ginny` (`bin.ginny → dist/index.js`). There are exactly
|
|
8
|
+
two ways to invoke it — the entry point reads a single positional
|
|
9
|
+
argument (`process.argv[2]`); there are **no option flags**.
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
ginny # interactive REPL (no arg)
|
|
13
|
+
ginny "your request" # one-shot: runs the request, then exits
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
- **REPL mode** (no arg): clears the screen (TTY only), prints a startup
|
|
17
|
+
banner, then loops on a `> ` prompt. Each non-empty line is processed
|
|
18
|
+
as a request; history is carried across turns.
|
|
19
|
+
- **One-shot mode** (one arg): runs that single request and exits. Wrap
|
|
20
|
+
multi-word requests in quotes.
|
|
21
|
+
|
|
22
|
+
### Interrupts
|
|
23
|
+
|
|
24
|
+
- **ESC** — interrupts the in-flight request and returns to the `> `
|
|
25
|
+
prompt without killing the REPL. (Listened for on both `keypress` and
|
|
26
|
+
raw `data`/SIGINT channels for cross-platform reliability.)
|
|
27
|
+
- **Ctrl+C** — also aborts an in-flight request; at the idle prompt it
|
|
28
|
+
exits the process.
|
|
29
|
+
|
|
30
|
+
The interrupt signal is forwarded into in-program I/O (`fns.fetch`,
|
|
31
|
+
`fns.llm`) and into web tools so a long network call unwinds cleanly.
|
|
32
|
+
|
|
33
|
+
### npm scripts (from `package.json`)
|
|
34
|
+
|
|
35
|
+
| Script | Command | Purpose |
|
|
36
|
+
|---|---|---|
|
|
37
|
+
| `build` | `npm run clean && node esbuild.config.cjs` | Bundle to `dist/index.js` (single ESM file + shebang). |
|
|
38
|
+
| `dev` | `tsx src/index.ts` | Run from source. |
|
|
39
|
+
| `start` | `tsx --conditions=source src/index.ts` | Run from source using workspace `source` exports. |
|
|
40
|
+
| `clean` | `rimraf dist tsconfig.tsbuildinfo` | Remove build output. |
|
|
41
|
+
| `typecheck` | `tsc --noEmit` | Type-check only. |
|
|
42
|
+
|
|
43
|
+
## First run in a directory
|
|
44
|
+
|
|
45
|
+
If `config.json` does not exist in the CWD, ginny:
|
|
46
|
+
|
|
47
|
+
1. Writes a `config.json` template.
|
|
48
|
+
2. Appends `config.json` and `ginny.log` to `.gitignore` (creating it if
|
|
49
|
+
needed).
|
|
50
|
+
3. Prints setup instructions and **exits** (no request is processed).
|
|
51
|
+
|
|
52
|
+
Populate at least one provider credential, then re-run. Example
|
|
53
|
+
`config.json`:
|
|
54
|
+
|
|
55
|
+
```json
|
|
56
|
+
{
|
|
57
|
+
"OPENAI_API_KEY": "sk-...",
|
|
58
|
+
"GIN_PROVIDER": "openai",
|
|
59
|
+
"GIN_MODEL": "gpt-4o-mini",
|
|
60
|
+
"TAVILY_API_KEY": "tvly-..."
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Providers
|
|
65
|
+
|
|
66
|
+
At least one provider must resolve at startup or ginny throws. The three
|
|
67
|
+
candidates:
|
|
68
|
+
|
|
69
|
+
- **openai** — enabled when `OPENAI_API_KEY` is set.
|
|
70
|
+
- **openrouter** — enabled when `OPENROUTER_API_KEY` is set.
|
|
71
|
+
- **aws** (Bedrock) — there is **no single env var**. ginny probes the
|
|
72
|
+
AWS SDK's standard credential chain at startup via a health check
|
|
73
|
+
(`ListFoundationModels`). Any working credential source enables it:
|
|
74
|
+
`aws sso login`, `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`, an
|
|
75
|
+
attached IAM role, `~/.aws/credentials`, or container credentials.
|
|
76
|
+
`AWS_REGION` defaults to `us-east-1`.
|
|
77
|
+
|
|
78
|
+
The startup banner reports which providers came up, which were skipped
|
|
79
|
+
(with reasons), the configured model IDs, and whether web research
|
|
80
|
+
(Tavily) is enabled.
|
|
81
|
+
|
|
82
|
+
## Configuration
|
|
83
|
+
|
|
84
|
+
Config values come from `config.json` in the CWD **or** from environment
|
|
85
|
+
variables. **Environment variables always win** on conflict. `config.json`
|
|
86
|
+
values are hydrated into `process.env` at startup before anything reads
|
|
87
|
+
them.
|
|
88
|
+
|
|
89
|
+
### Keys recognized in `config.json` (and as env vars)
|
|
90
|
+
|
|
91
|
+
These are the typed fields in the `config.json` template:
|
|
92
|
+
|
|
93
|
+
| Key | Default | Purpose |
|
|
94
|
+
|---|---|---|
|
|
95
|
+
| `OPENAI_API_KEY` | — | Enable OpenAI provider. |
|
|
96
|
+
| `OPENROUTER_API_KEY` | — | Enable OpenRouter provider. |
|
|
97
|
+
| `AWS_ACCESS_KEY_ID` | — | Optional explicit AWS key (chain usually suffices). |
|
|
98
|
+
| `AWS_SECRET_ACCESS_KEY` | — | Optional explicit AWS secret. |
|
|
99
|
+
| `AWS_REGION` | `us-east-1` | Bedrock region. |
|
|
100
|
+
| `TAVILY_API_KEY` | — | Enable `web_search` / `web_get_page` and the `research` tool. |
|
|
101
|
+
| `GIN_PROVIDER` | — | Preferred provider (`openai` \| `openrouter` \| `aws`). |
|
|
102
|
+
| `GIN_MODEL` | — | Pin a model id; fallback for any sub-agent without an override. |
|
|
103
|
+
| `GIN_SEARCH_THRESHOLD` | `20` | Catalog size at/below which a search returns all entries (above it, keyword-scored top-N). |
|
|
104
|
+
| `GIN_TOOL_ITERATIONS` | `100` | Max tool-call iterations per prompt run. |
|
|
105
|
+
|
|
106
|
+
### Env-only variables (not in the template)
|
|
107
|
+
|
|
108
|
+
| Variable | Default | Purpose |
|
|
109
|
+
|---|---|---|
|
|
110
|
+
| `GIN_PROGRAMMER_MODEL` | — | Model id for the programmer sub-agent. |
|
|
111
|
+
| `GIN_DESIGNER_MODEL` | — | Model id for the designer (functions) sub-agent. |
|
|
112
|
+
| `GIN_ARCHITECT_MODEL` | — | Model id for the architect (types) sub-agent. |
|
|
113
|
+
| `GIN_DBA_MODEL` | — | Model id for the dba (vars) sub-agent. |
|
|
114
|
+
| `GIN_RESEARCHER_MODEL` | — | Model id for the researcher sub-agent. |
|
|
115
|
+
| `GIN_LLM_MODEL` | — | Model id for in-program `fns.llm` calls. |
|
|
116
|
+
| `GIN_MAX_WARNINGS` | `5` | Max validation warnings allowed on a saved fn (`finish` rejects above this). |
|
|
117
|
+
| `GIN_MAX_COMPLEXITY` | `400` | Max structural complexity for a saved fn body (`finish` rejects above this). |
|
|
118
|
+
| `GIN_WRITE_MAX_ARGS_LENGTH` | `16384` | Byte cap on the raw `write` tool args (guards against wire double-encoding). |
|
|
119
|
+
| `GIN_LOG_FULL_PAYLOAD` | unset | When set, logs full request/response payloads (large; for debugging 400s). |
|
|
120
|
+
|
|
121
|
+
Per-sub-agent model resolution: each agent reads `GIN_<KEY>_MODEL`
|
|
122
|
+
(`KEY` ∈ `PROGRAMMER`, `DESIGNER`, `ARCHITECT`, `DBA`, `RESEARCHER`,
|
|
123
|
+
`LLM`), falling back to `GIN_MODEL`, falling back to the AI model
|
|
124
|
+
registry's default selection. This lets the heavyweight programmer run on
|
|
125
|
+
a strong model while catalog curators run on something cheaper:
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
GIN_PROGRAMMER_MODEL=gpt-5
|
|
129
|
+
GIN_DBA_MODEL=gpt-4o-mini
|
|
130
|
+
GIN_RESEARCHER_MODEL=gpt-4o-mini ginny "build a small task tracker"
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
## Persistence — the on-disk catalog
|
|
134
|
+
|
|
135
|
+
Everything the agent saves is one JSON file per name, in three
|
|
136
|
+
directories relative to the **current working directory**. The filename
|
|
137
|
+
**is** the identity (no internal id field needed).
|
|
138
|
+
|
|
139
|
+
```
|
|
140
|
+
./types/Task.json # a gin TypeDef
|
|
141
|
+
./fns/factorial.json # a function (TypeDef whose body is at call.get)
|
|
142
|
+
./vars/apiBaseUrl.json # a persistent var: { type, value, docs }
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
- You can hand-edit any of these between sessions; the next run picks up
|
|
146
|
+
the changes. Drop a new file into a directory by hand and ginny
|
|
147
|
+
discovers it on the next catalog search.
|
|
148
|
+
- A saved function becomes a **callable top-level global** for the rest of
|
|
149
|
+
the session (and future sessions on load) — invoked by its bare name,
|
|
150
|
+
not under `fns.*`.
|
|
151
|
+
|
|
152
|
+
Example `./vars/apiBaseUrl.json`:
|
|
153
|
+
|
|
154
|
+
```json
|
|
155
|
+
{
|
|
156
|
+
"type": { "name": "text", "options": { "pattern": "^https?://" } },
|
|
157
|
+
"value": "https://api.example.com",
|
|
158
|
+
"docs": "production API root"
|
|
159
|
+
}
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
See [aeye-ginny-api.md](./aeye-ginny-api.md) for the function and type
|
|
163
|
+
file shapes in detail.
|
|
164
|
+
|
|
165
|
+
## Logging
|
|
166
|
+
|
|
167
|
+
Each session writes a verbose timeline to `./ginny.log` (truncated at
|
|
168
|
+
startup). Tool inputs/outputs, full validation problems, zod parse
|
|
169
|
+
errors, retry/backoff events, and stack traces land there. The terminal
|
|
170
|
+
view stays compact (one short line per error). Errors in the terminal are
|
|
171
|
+
stamped with a 6-character id; `grep <id> ginny.log` recovers the full
|
|
172
|
+
record. Memory-probe lines (`[mem] ...`) are emitted for leak hunting.
|
|
173
|
+
|
|
174
|
+
## Building from source
|
|
175
|
+
|
|
176
|
+
```bash
|
|
177
|
+
git clone https://github.com/ClickerMonkey/aeye.git
|
|
178
|
+
cd aeye
|
|
179
|
+
npm install
|
|
180
|
+
cd packages/ginny
|
|
181
|
+
npm run start # dev run (tsx --conditions=source)
|
|
182
|
+
npm run build # bundled dist/index.js with shebang
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
The production build is a single ESM file with a Node shebang; the global
|
|
186
|
+
install (`npm i -g @aeye/ginny`) links `ginny` straight to it.
|
package/aeye-ginny.md
ADDED
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# @aeye/ginny — LLM Reference (Overview & Index)
|
|
2
|
+
|
|
3
|
+
> Audience: an LLM (or an agent) that needs to understand, run, or reason
|
|
4
|
+
> about `@aeye/ginny`. Everything here is verified against the source in
|
|
5
|
+
> `packages/ginny/src`. Do not invent flags, env vars, or APIs beyond
|
|
6
|
+
> what these files document.
|
|
7
|
+
|
|
8
|
+
## What ginny is
|
|
9
|
+
|
|
10
|
+
`@aeye/ginny` is a **CLI that turns natural-language requests into
|
|
11
|
+
executable [gin](../gin) programs**. You type a request in plain English;
|
|
12
|
+
ginny writes a gin program (a JSON expression tree) to satisfy it, tests
|
|
13
|
+
it against sample inputs, and returns the result. Types, functions, and
|
|
14
|
+
vars the agent creates are persisted as JSON files in the current working
|
|
15
|
+
directory, so a typed catalog of reusable code grows across sessions.
|
|
16
|
+
|
|
17
|
+
- Package name: `@aeye/ginny`
|
|
18
|
+
- Binary: `ginny` (maps to `dist/index.js`, an ESM file with a Node shebang)
|
|
19
|
+
- License: GPL-3.0
|
|
20
|
+
- Node engine: `>=18.0.0`
|
|
21
|
+
- It is an **application/CLI, not a library** — see
|
|
22
|
+
[aeye-ginny-api.md](./aeye-ginny-api.md) for what that means for
|
|
23
|
+
programmatic use.
|
|
24
|
+
|
|
25
|
+
## When to use ginny
|
|
26
|
+
|
|
27
|
+
Use ginny when you want to:
|
|
28
|
+
|
|
29
|
+
- Generate, test, and persist small typed programs from natural language
|
|
30
|
+
without writing gin `ExprDef` JSON by hand.
|
|
31
|
+
- Build a reusable, CWD-local catalog of typed functions / types / vars
|
|
32
|
+
that survives across sessions and is hand-editable.
|
|
33
|
+
- Call HTTP APIs with typed response parsing, invoke an LLM with
|
|
34
|
+
structured typed output, or prompt the user interactively — all from
|
|
35
|
+
inside generated programs (`fns.fetch`, `fns.llm`, `fns.ask`).
|
|
36
|
+
- Study a reference embedding of `@aeye/gin` + `@aeye/ai`: a recursive
|
|
37
|
+
multi-sub-agent system with strict-mode tool schemas and multi-provider
|
|
38
|
+
model selection.
|
|
39
|
+
|
|
40
|
+
Do **not** use ginny as an importable library — importing its entry
|
|
41
|
+
module runs the CLI. To embed the same capabilities, use `@aeye/gin`
|
|
42
|
+
directly.
|
|
43
|
+
|
|
44
|
+
## Quick start
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
npm install -g @aeye/ginny
|
|
48
|
+
cd my-project
|
|
49
|
+
ginny # interactive REPL
|
|
50
|
+
ginny "add 2 and 3" # one-shot (single positional arg)
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
On the **first run in a directory**, ginny scaffolds a `config.json`
|
|
54
|
+
template, adds `config.json` and `ginny.log` to `.gitignore`, prints
|
|
55
|
+
setup instructions, and exits. Populate at least one provider key and
|
|
56
|
+
re-run. Full details: [aeye-ginny-cli.md](./aeye-ginny-cli.md).
|
|
57
|
+
|
|
58
|
+
## How it works (one-paragraph pipeline)
|
|
59
|
+
|
|
60
|
+
The REPL/one-shot entry point appends your request to a conversation
|
|
61
|
+
history and streams the **programmer** sub-agent. The programmer writes a
|
|
62
|
+
gin program via the `write` tool, runs it via `test`, and persists it via
|
|
63
|
+
`finish`. When it needs types, reusable functions, or named vars not
|
|
64
|
+
already in scope, it delegates to specialist sub-agents — **architect**
|
|
65
|
+
(types), **designer** (functions), **dba** (vars), and **researcher**
|
|
66
|
+
(web) — each of which searches the on-disk catalog and creates new
|
|
67
|
+
entries when nothing matches. The designer authors a new function body by
|
|
68
|
+
**recursively spawning another programmer** (bounded to 3 levels deep).
|
|
69
|
+
Everything is typed end-to-end inside gin's type system, and structured
|
|
70
|
+
outputs are produced through Zod schemas so the model cannot emit invalid
|
|
71
|
+
expressions. See [aeye-ginny-architecture.md](./aeye-ginny-architecture.md).
|
|
72
|
+
|
|
73
|
+
## Relationship to other @aeye packages
|
|
74
|
+
|
|
75
|
+
- **`@aeye/gin`** — the typed-program runtime ginny builds on: the type
|
|
76
|
+
system, the expression engine (`engine.run`), and the Zod schema
|
|
77
|
+
generation the agents use to author valid programs. ginny is a thin
|
|
78
|
+
layer of tool/prompt definitions over gin's public API.
|
|
79
|
+
- **`@aeye/core`** — the prompt / tool / agent primitives (`ai.prompt`,
|
|
80
|
+
`ai.tool`, `Message`, `ToolInterrupt`, prompt-event streaming) that
|
|
81
|
+
every ginny sub-agent is built from.
|
|
82
|
+
- **`@aeye/ai`** — the `AI` instance: provider registration, model
|
|
83
|
+
selection, metadata, and hooks.
|
|
84
|
+
- **`@aeye/openai`, `@aeye/openrouter`, `@aeye/aws`** — the three
|
|
85
|
+
providers ginny can enable.
|
|
86
|
+
- **`@aeye/models`** — the model registry plus `strictSupport`, which
|
|
87
|
+
opts strict-capable model families into grammar-constrained tool inputs.
|
|
88
|
+
|
|
89
|
+
## Index of detailed docs
|
|
90
|
+
|
|
91
|
+
| File | Covers |
|
|
92
|
+
|---|---|
|
|
93
|
+
| [aeye-ginny-cli.md](./aeye-ginny-cli.md) | Running the CLI, REPL vs one-shot, interrupts, first-run scaffold, config.json, all environment variables, persistence/catalog layout, logging, building from source. |
|
|
94
|
+
| [aeye-ginny-architecture.md](./aeye-ginny-architecture.md) | The sub-agent council, each agent's tools, the write/test/finish loop, recursive function authoring, depth cap, complexity/warning gates, catalog search behavior. |
|
|
95
|
+
| [aeye-ginny-api.md](./aeye-ginny-api.md) | Built-in program globals (`fns.fetch` / `fns.llm` / `fns.log` / `fns.ask`, `vars.*`, saved fns), on-disk JSON shapes, programmatic-use note, gotchas. |
|
|
96
|
+
|
|
97
|
+
## Source map (for deeper reading)
|
|
98
|
+
|
|
99
|
+
- `src/index.ts` — CLI entry: REPL loop, one-shot, ESC/Ctrl+C interrupts, startup banner.
|
|
100
|
+
- `src/ai.ts` — AI instance, provider probing, hooks, native wiring (`fns.*`).
|
|
101
|
+
- `src/config.ts` — `config.json` load/scaffold, `.gitignore` management, env hydration.
|
|
102
|
+
- `src/model-selection.ts` — per-sub-agent model resolution, tool-iteration cap.
|
|
103
|
+
- `src/store.ts` — CWD-relative catalog read/write/search.
|
|
104
|
+
- `src/context.ts` — the `Ctx` shared across sub-agents; `MAX_PROGRAMMER_DEPTH`.
|
|
105
|
+
- `src/prompts/*` — the sub-agent definitions (programmer, architect, designer, dba, researcher).
|
|
106
|
+
- `src/tools/*` — `write`, `test`, `finish`, `research`, `find-or-create-*`, `edit-type`, `ask`, web tools, etc.
|
|
107
|
+
- `src/natives/*` — `fns.fetch`, `fns.llm`, `fns.log`, `fns.ask` implementations.
|
|
108
|
+
- `src/consumer.ts` — interactive type-walker behind `fns.ask`.
|
|
109
|
+
- `src/progress.ts`, `src/event-display.ts`, `src/logger.ts` — terminal/log output.
|