@interf/compiler 0.6.7 → 0.6.8

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.
Files changed (3) hide show
  1. package/README.md +137 -60
  2. package/dist/cli/commands/init.js +1 -1
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -1,30 +1,32 @@
1
1
  # Interf
2
2
 
3
- Interf prepares context for your agents.
4
- Use it to check whether your files are ready for the work you want your agents to do.
3
+ Interf prepares portable context for your agents.
4
+ Check the source files first. Build portable context when the agent misses evidence, loses links across files, or sounds confident without seeing the full picture.
5
5
 
6
- **Files alone are not automatically ready for agent work.**
6
+ **The files can be right. The agent can still be wrong.**
7
7
 
8
- Coding agents now run real work from folders of PDFs, exports, notes, and transcripts. Those folders can still be missing the structure that work needs.
8
+ Agents now run real work from folders of PDFs, exports, notes, and transcripts. The failure often shows up late: missed evidence, shallow analysis, bad comparisons, or answers that sound confident but are wrong.
9
9
 
10
- A chart buried inside a market-report PDF can be obvious to a human analyst and easy for an agent to miss. Interf checks the source files first, then builds portable context when the raw files are not enough.
10
+ A chart inside one PDF can be obvious to a human analyst and easy for an agent to miss. Across the folder, the real problem is rarely one missing fact. The agent never assembles the full picture from the files on its own.
11
11
 
12
- `Interf Compiler` is the local, open-source runtime behind that loop. It uses your local agent to organize the files for one piece of work and build portable context next to them. `interf test` scores the source files and the portable context on the same questions.
12
+ `Interf Compiler` is the local, open-source runtime that runs context-preparation workflows on your files. A workflow tells Interf how to process, organize, and structure those files for agent use. Your local agent runs each stage. Interf Compiler runs the pipeline and enforces the output shape. `interf test` scores the result on your own questions. The portable context is a proof, not a promise.
13
13
 
14
14
  ```text
15
- your-folder/
16
- market-report/
15
+ project-root/
16
+ bristol-office-analysis/
17
17
  report.pdf
18
18
  notes.md
19
19
  exports/
20
- interf.json # saved setup and questions for this work
20
+ interf.json # main config: works, source paths, questions, workflow choices, and defaults
21
21
  interf/
22
- market-report/ # portable context your agent starts from
22
+ bristol-office-analysis/ # portable context your agent starts from
23
23
  tests/
24
- market-report/ # source-files vs portable-context scores
24
+ bristol-office-analysis/ # saved source-files vs portable-context comparisons
25
25
  ```
26
26
 
27
- ## What a run looks like
27
+ The project root is the control plane. Your agent starts from `interf/<work>/` when the source files are not enough.
28
+
29
+ ## What a Run Looks Like
28
30
 
29
31
  A recent public run — one PDF market report, two questions, two agents on the same setup — produced:
30
32
 
@@ -37,18 +39,17 @@ A recent public run — one PDF market report, two questions, two agents on the
37
39
 
38
40
  Codex passed on the raw files; Claude Code only passed after Interf prepared the portable context. Both numbers come from `interf test`, which scores the same questions against the source files and the portable context.
39
41
 
40
- The table is a sample, not a leaderboard. Run it on your own files. If you run more than one local agent, the same pass gives you a fair comparison between them on the same files.
42
+ That gives you a readiness signal for the work and a fair comparison on the same files.
41
43
 
42
- ## The loop
44
+ The table is a sample, not a leaderboard. Run it on your own files. If you run more than one local agent, the same pass gives you a fair comparison between them on the same files.
43
45
 
44
- 1. Drop the files for one piece of work under a folder.
45
- 2. Run `interf` and describe the work. Interf recommends a few questions you can verify from the files.
46
- 3. `interf test --target raw` scores the source files.
47
- 4. `interf compile` builds portable context next to the files.
48
- 5. `interf test` scores the portable context on the same questions.
49
- 6. Use whichever side did better.
46
+ ## Design Choices
50
47
 
51
- Step 3 is optional. It is the honest first check: sometimes the files are already enough, and Interf will say so instead of building something you do not need.
48
+ - `Check before build`: source files are sometimes already enough. Interf will say so.
49
+ - `Prove the full picture`: every build is scored on your own questions. If the portable context does not help, `interf test` tells you.
50
+ - `File over app`: the portable context is a local folder next to the source files. Inspect it, diff it, version it.
51
+ - `Bring your own AI`: use Claude Code, Codex, or another local agent.
52
+ - `Explicit`: no hidden store, no hidden index. The portable context is plain files on disk.
52
53
 
53
54
  ## Install
54
55
 
@@ -59,25 +60,25 @@ interf # opens the setup wizard in the current folder
59
60
 
60
61
  Requires Node.js 20+ and a local coding agent such as Claude Code or Codex. Run `interf doctor --live` if the executor is not detected.
61
62
 
62
- ## Core commands
63
+ ## Quick Start
63
64
 
64
- - `interf` or `interf init` — open the wizard for the current folder
65
- - `interf compile` — build portable context for your agents
66
- - `interf test` — score source files and portable context on the same questions
67
- - `interf create workflow` — draft or copy a reusable workflow
68
- - `interf create dataset` — add another piece of work to this project
69
- - `interf list` — list the pieces of work in this project
70
- - `interf status` — show deterministic health
71
- - `interf doctor` — check the local agent executor
72
- - `interf verify <check>` — deterministic verification for automation
73
- - `interf reset <scope>` — reset generated state while keeping source files
65
+ 1. Run `interf` in the project root.
66
+ 2. Pick the source folder for one work.
67
+ 3. Describe what the agent should do with those files.
68
+ 4. Review the suggested questions.
69
+ 5. Run `interf test --target raw` to check the source files.
70
+ 6. Run `interf compile` to build portable context.
71
+ 7. Run `interf test` again to compare source files and portable context on the same questions.
72
+ 8. If the portable context does better, point your agent at `interf/<work>/`.
73
+
74
+ If the source files already pass, stop there. Interf is allowed to tell you that you do not need portable context for that work.
74
75
 
75
- ## Portable context
76
+ ## Portable Context
76
77
 
77
- `interf/<work>/` is the folder your agent starts from when the raw files are not enough. For the built-in `interf` workflow, it includes:
78
+ `interf/<work>/` is the local folder your agent starts from when the source files are not enough. For the built-in `interf` workflow, it includes:
78
79
 
79
80
  ```text
80
- interf/market-report/
81
+ interf/bristol-office-analysis/
81
82
  AGENTS.md # how to use this folder
82
83
  CLAUDE.md # same guidance for Claude Code
83
84
  raw/ # snapshot of the source files for this work
@@ -86,19 +87,101 @@ interf/market-report/
86
87
  knowledge/ # linked notes built from the files
87
88
  ```
88
89
 
89
- Interf builds next to the source files; it does not replace them. The portable context is a sibling folder you can version, inspect line-by-line, or hand to a different agent.
90
+ The source files stay the source of truth. Interf builds next to them; it does not replace them.
90
91
 
91
- It carries its own `raw/` snapshot for verification. Any CLI that reads a local directory — Claude Code, Codex, your own — can work from it.
92
+ The portable context is a sibling folder you can inspect, diff, version, or hand to a different agent. The portable context carries its own `raw/` snapshot, so the evidence the agent works from stays attached to the result.
92
93
 
93
- The method that builds the portable context is a workflow. In plain language, it is how Interf summarizes the files, extracts structure, and links notes for agent use.
94
+ ## Workflow Packages
94
95
 
95
- Technically, the workflow is a workflow package; the folder shape it writes is the context interface; the built folder is the compiled context. Run `interf create workflow` if the built-in method is not enough for your work. Most users only touch `interf/<work>/`.
96
+ A workflow is Interf's preparation method for a kind of work. It tells the compiler how to process the source files and what folder shape to build for the agent. The workflow declares the compilation stages. Your local agent runs each one. The compiler writes the result as one folder on disk.
96
97
 
97
- ## Questions
98
+ A **context interface** is the shape of that output — the folder tree, the named files, and the rule that every one of them must exist on disk before the build is called done. The workflow defines the interface. The compiler enforces it.
99
+
100
+ The built-in `interf` workflow is the default. Run `interf create workflow` to draft a reusable workflow package for a different kind of work — a different method, a different output shape, or both.
101
+
102
+ ```text
103
+ interf/workflows/office-analysis/
104
+ workflow.json # method: how to process and organize the files
105
+ workflow.schema.json # output contract: what folder shape the compiler must build
106
+ README.md # what this workflow is for, for humans and agents
107
+ compile/
108
+ stages/
109
+ summarize/ # define your own stages here
110
+ structure/
111
+ shape/
112
+ use/
113
+ query/ # how your agent reads the portable context
114
+ improve/ # how Interf revises this workflow if questions still fail
115
+ ```
116
+
117
+ Think of it as method -> output shape.
118
+
119
+ - `workflow.json` describes the method: expected inputs, stages, and how the files should be processed.
120
+ - `workflow.schema.json` describes the output contract: the folder shape and outputs the compiler must build.
121
+ - `compile/stages/<stage>/` is where you author one folder per stage — a small, specific job like `summarize` or `structure`. You write the instructions; the compiler runs them with your local agent.
122
+ - `use/query/` holds the instructions your agent follows when it reads the portable context for live work.
123
+ - `improve/` holds the instructions Interf follows when the first build does not pass and the workflow itself needs editing.
124
+
125
+ A workflow package is the reusable preparation method. Interf Compiler runs it on your files. Your local agent runs each stage. The result is a local folder your agents can read.
126
+
127
+ ## Compiler Primitives
128
+
129
+ Every workflow runs on the same three primitives. Interf Compiler enforces the contract. The workflow chooses the method.
130
+
131
+ ### Input snapshot
132
+
133
+ The workflow declares what source files it expects — one PDF, a folder of mixed exports, a tree of notes. Interf Compiler copies those inputs into `raw/` before any stage runs. The evidence stays attached to the result.
134
+
135
+ ### Context interface
136
+
137
+ The workflow declares the folder shape the agent must read. Interf Compiler checks on disk that the shape holds before the build is called done. If a stage writes nothing, the build fails loudly.
138
+
139
+ ### Stage execution
140
+
141
+ The workflow declares ordered compilation stages — small, specific jobs like `summarize`, `structure`, `shape`. You write the instructions per stage. Interf Compiler runs each one through your local agent and checks the output before moving to the next.
142
+
143
+ The context interface is the key guarantee. The shape holds on disk, or `interf test` reports the gap on your own questions.
144
+
145
+ ## Self-Improving Workflows
146
+
147
+ When the first build still misses questions, Interf edits the workflow package itself and compiles again. Same files, same questions, different preparation. The workflow is the unit of improvement — not just the output folder.
148
+
149
+ Interf saves every scored run under `interf/tests/<work>/`. You can inspect what changed and why a later build did better.
150
+
151
+ ## How the Pieces Fit
98
152
 
99
- Interf runs question-and-answer checks.
153
+ - `interf.json` is the project control file. It names the work, points at the source files, saves the questions, and selects the workflow.
154
+ - A workflow package is the reusable preparation method.
155
+ - `workflow.json` defines that method.
156
+ - `workflow.schema.json` defines the output contract, or context interface, the compiler must build.
157
+ - `Interf Compiler` is the local runtime. It runs the workflow, your agent runs each stage, and the portable context lands next to the source files.
158
+ - The portable context is the local folder built for your agents. Technically, that folder is the compiled context.
100
159
 
101
- In the flow, they feel like plain questions. In `interf.json`, they live under `checks[]` — small facts that define what "good enough" means for this work.
160
+ ## interf.json
161
+
162
+ `interf.json` is the main config file in the project root. Each entry describes one work: the source path, the saved questions, the workflow that prepares the context, and optional defaults.
163
+
164
+ ```text
165
+ {
166
+ "datasets": [
167
+ {
168
+ "name": "bristol-office-analysis",
169
+ "path": "./bristol-office-analysis",
170
+ "about": "Read the report and answer the saved questions.",
171
+ "workflow": "interf",
172
+ "checks": [
173
+ { "question": "...", "answer": "..." }
174
+ ]
175
+ }
176
+ ]
177
+ }
178
+ ```
179
+
180
+ The `workflow` field is the key choice per work. Set it to `interf` for the built-in workflow, or to a workflow you have authored. A different workflow is a different method and a different output shape. Same files, different portable context.
181
+
182
+ ## Questions
183
+
184
+ In the flow, they look like plain questions. In `interf.json`, they live under `checks[]`.
102
185
 
103
186
  They should be small, verifiable facts you already know from the files:
104
187
 
@@ -111,7 +194,7 @@ Interf proposes an initial set from the files and the work description. You conf
111
194
  A maintained public test example in this repo stores them like this:
112
195
 
113
196
  <!-- PUBLIC_TEST_CHECKS:START -->
114
- ```jsonc
197
+ ```text
115
198
  {
116
199
  "datasets": [
117
200
  {
@@ -134,34 +217,28 @@ A maintained public test example in this repo stores them like this:
134
217
  ```
135
218
  <!-- PUBLIC_TEST_CHECKS:END -->
136
219
 
137
- ## Self-improving loops
138
-
139
- One compile pass is not always enough. If the portable context still fails some questions, Interf can revise the workflow and compile again: same files, same questions, different preparation.
140
-
141
- Each loop edits the workflow between attempts. Interf keeps every scored run under `interf/tests/<work>/`, so you can diff why one version did better than the next.
142
-
143
- ## Design choices
220
+ ## What Interf Is Not
144
221
 
145
- - `Explicit`: portable context is a folder on disk you can inspect, diff, and version.
146
- - `File over app`: Interf builds next to the source files.
147
- - `Bring your own AI`: use Claude Code, Codex, or another local agent.
148
- - `Proof over vibes`: `interf test` scores source files and portable context on the same questions.
149
- - `Source files stay the source of truth`: Interf builds next to them; it does not replace them.
150
-
151
- ## What Interf is not
152
-
153
- - Not a second brain or memory product. One folder per piece of work; nothing global.
222
+ - Not a second brain or memory product. One local folder per work; nothing global.
154
223
  - Not a vector store or RAG server. The portable context is plain files.
155
224
  - Not a hosted context layer. Interf runs locally and `interf/` is yours.
156
225
  - Not an agent harness. Interf prepares the folder; your existing agent reads it.
157
226
  - Not a public leaderboard. Every score comes from your files, your questions, and your agent.
158
227
 
228
+ ## Useful Commands
229
+
230
+ - `interf` or `interf init` — open the wizard and save the first setup
231
+ - `interf compile` — build portable context for your agents
232
+ - `interf test` — compare source files and portable context on the same questions
233
+ - `interf create workflow` — draft a reusable workflow package
234
+ - `interf doctor --live` — verify the local executor
235
+
159
236
  ## Docs
160
237
 
161
238
  - [src/packages/README.md](./src/packages/README.md) — system map
162
239
  - [src/packages/compiler/PACKAGE.md](./src/packages/compiler/PACKAGE.md) — compiler primitives and runtime contract
163
240
  - [src/packages/workflow-package/PACKAGE.md](./src/packages/workflow-package/PACKAGE.md) — workflow package model
164
- - [src/packages/workflow-authoring/PACKAGE.md](./src/packages/workflow-authoring/PACKAGE.md) — workflow authoring and self-improving loops
241
+ - [src/packages/workflow-authoring/PACKAGE.md](./src/packages/workflow-authoring/PACKAGE.md) — workflow authoring and workflow improvement
165
242
 
166
243
  Contributors: see [CONTRIBUTING.md](./CONTRIBUTING.md).
167
244
 
package/dist/cli/commands/init.js CHANGED
@@ -456,7 +456,7 @@ export const initCommand = {
456
456
  };
457
457
  export async function runInitCommand() {
458
458
  p.intro(chalk.bold("Interf"));
459
- p.log.info("Interf prepares context for your agents from the source folder you choose. Start with the work, review the suggested questions, check the source files first, and build a local folder when the files need more structure.");
459
+ p.log.info("Interf prepares portable context for your agents from the source folder you choose. Start with the work, review the suggested questions, check the source files first, and build a local folder when the files need more structure.");
460
460
  const cwd = process.cwd();
461
461
  const detected = detectInterf(cwd);
462
462
  const sourcePath = detected ? resolveSourceControlPath(detected.path) : cwd;
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@interf/compiler",
3
- "version": "0.6.7",
4
- "description": "Interf prepares context for your agents by checking your files first, building a local folder when needed, and using self-improving loops until more questions pass.",
3
+ "version": "0.6.8",
4
+ "description": "Interf prepares portable context for your agents by checking your files first, building a local folder when needed, and using self-improving loops until more questions pass.",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "interf": "dist/bin.js"