@interf/compiler 0.6.7 → 0.6.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.
Files changed (3) hide show
  1. package/README.md +128 -74
  2. package/dist/cli/commands/init.js +1 -1
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -1,54 +1,35 @@
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.
5
4
 
6
- **Files alone are not automatically ready for agent work.**
5
+ Agents now run real work from folders of PDFs, exports, notes, and transcripts. They don't reliably assemble the full picture from them: missed evidence, links lost across files, or answers that sound confident but are wrong. A chart inside one PDF can be obvious to a human analyst and easy for an agent to miss.
7
6
 
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.
7
+ The fix is structure: summarize the files, organize by category, link what belongs together. You tell Interf Compiler how — that's a compilation workflow.
9
8
 
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.
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.
9
+ `Interf Compiler` is the local, open-source runtime that runs compilation workflows on your files. Your local agent executes each stage. The compiler builds portable context — a local folder your agent reads. If the first build misses your questions, Interf improves the compilation workflow and builds again.
13
10
 
14
11
  ```text
15
- your-folder/
16
- market-report/
12
+ project-root/
13
+ bristol-office-analysis/
17
14
  report.pdf
18
15
  notes.md
19
16
  exports/
20
- interf.json # saved setup and questions for this work
17
+ interf.json # main config: works, source paths, questions, workflow choices, and defaults
21
18
  interf/
22
- market-report/ # portable context your agent starts from
19
+ bristol-office-analysis/ # portable context your agent starts from
23
20
  tests/
24
- market-report/ # source-files vs portable-context scores
21
+ bristol-office-analysis/ # saved source-files vs portable-context comparisons
25
22
  ```
26
23
 
27
- ## What a run looks like
28
-
29
- A recent public run — one PDF market report, two questions, two agents on the same setup — produced:
30
-
31
- <!-- PUBLIC_BENCHMARK_TABLE:START -->
32
- | Agent | Source files | Portable context |
33
- | --- | --- | --- |
34
- | Codex (GPT-5.4, xhigh) | `2/2` | `2/2` |
35
- | Claude Code (Claude Opus 4.6, max) | `0/2` | `2/2` |
36
- <!-- PUBLIC_BENCHMARK_TABLE:END -->
37
-
38
- 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
-
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.
24
+ The project root is the control plane. Your agent starts from `interf/<work>/` when the source files are not enough.
41
25
 
42
- ## The loop
26
+ ## Design Choices
43
27
 
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.
50
-
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.
28
+ - `Check before build`: run `interf test --target raw` first — sometimes the source files already pass on your questions.
29
+ - `Scored on your own questions`: every build is checked against questions you wrote from the files. If the portable context does not help, `interf test` tells you.
30
+ - `File over app`: the portable context is a local folder next to the source files. Inspect it, diff it, version it.
31
+ - `Bring your own AI`: use Claude Code, Codex, or another local agent.
32
+ - `Explicit`: no hidden store, no hidden index. The portable context is plain files on disk.
52
33
 
53
34
  ## Install
54
35
 
@@ -59,25 +40,25 @@ interf # opens the setup wizard in the current folder
59
40
 
60
41
  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
42
 
62
- ## Core commands
43
+ ## Quick Start
63
44
 
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
45
+ 1. Run `interf` in the project root.
46
+ 2. Pick the source folder for one piece of agent work.
47
+ 3. Describe what the agent should do with those files.
48
+ 4. Review the suggested questions.
49
+ 5. Run `interf test --target raw` to score the source files.
50
+ 6. Run `interf compile` to build portable context.
51
+ 7. Run `interf test` again to compare source files and portable context on the same questions.
52
+ 8. If the portable context does better, point your agent at `interf/<work>/`.
53
+
54
+ By default, Interf uses the built-in `interf` compilation workflow. Create your own compilation workflow only when the built-in method is not enough for the work, or you need a different output.
74
55
 
75
- ## Portable context
56
+ ## Portable Context
76
57
 
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:
58
+ `interf/<work>/` is the local folder Interf Compiler builds from your files — a context layer your agents navigate, not a replacement for your files. For the built-in `interf` workflow, it includes:
78
59
 
79
60
  ```text
80
- interf/market-report/
61
+ interf/bristol-office-analysis/
81
62
  AGENTS.md # how to use this folder
82
63
  CLAUDE.md # same guidance for Claude Code
83
64
  raw/ # snapshot of the source files for this work
@@ -86,19 +67,98 @@ interf/market-report/
86
67
  knowledge/ # linked notes built from the files
87
68
  ```
88
69
 
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.
70
+ The source files stay the source of truth. Interf builds next to them; it does not replace them.
90
71
 
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.
72
+ The portable context is a 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
73
 
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.
74
+ ## Workflow Packages
94
75
 
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>/`.
76
+ A compilation workflow is how you tell Interf Compiler to organize and structure your files so your agents can reliably work from them. The built-in `interf` workflow covers common cases. Create your own when you need a different method, a different output, or both.
96
77
 
97
- ## Questions
78
+ Run `interf create workflow` to draft a reusable workflow package.
79
+
80
+ ```text
81
+ interf/workflows/office-analysis/
82
+ workflow.json # method: how to process and organize the files
83
+ workflow.schema.json # output contract: what files and folders the output must contain
84
+ README.md # what this compilation workflow is for, for humans and agents
85
+ compile/
86
+ stages/
87
+ summarize/ # define your own stages here
88
+ structure/
89
+ shape/
90
+ use/
91
+ query/ # how your agent reads the portable context
92
+ improve/ # how Interf revises this compilation workflow if questions still fail
93
+ ```
94
+
95
+ Think of it as method -> output shape.
96
+
97
+ - `workflow.json` describes the method: expected inputs, stages, and how the files should be processed.
98
+ - `workflow.schema.json` describes the output contract: what files and folders the output must contain. Technically, this is the `context interface`, declared in `workflow.schema.json` and enforced by the compiler.
99
+ - `compile/stages/<stage>/` is where you author one folder per stage — a small, specific phase like `summarize` or `structure`. You write the instructions; the compiler runs them with your local agent.
100
+ - `use/query/` holds the instructions your agent follows when it reads the portable context for live work.
101
+ - `improve/` holds the instructions Interf follows when the first build misses and the compilation workflow itself needs editing.
102
+
103
+ A workflow package bundles a compilation workflow. Interf Compiler runs it on your files. Your local agent runs each stage. The result is a local folder your agents can read.
104
+
105
+ ## What a Run Looks Like
106
+
107
+ A recent public run — one PDF market report, two questions, two agents on the same setup — produced:
108
+
109
+ <!-- PUBLIC_BENCHMARK_TABLE:START -->
110
+ | Agent | Source files | Portable context |
111
+ | --- | --- | --- |
112
+ | Codex (GPT-5.4, xhigh) | `2/2` | `2/2` |
113
+ | Claude Code (Claude Opus 4.6, max) | `0/2` | `2/2` |
114
+ <!-- PUBLIC_BENCHMARK_TABLE:END -->
98
115
 
99
- Interf runs question-and-answer checks.
116
+ 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.
117
+
118
+ That gives you a readiness signal for the work and a fair comparison on the same files.
119
+
120
+ 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.
121
+
122
+ ## Self-Improving Workflows
123
+
124
+ When the first build still misses questions, Interf edits the workflow package itself and compiles again. Same files, same questions, different preparation.
125
+
126
+ Interf saves every scored run under `interf/tests/<work>/`. You can inspect what changed and why a later build did better.
127
+
128
+ ## How the Pieces Fit
129
+
130
+ - `interf.json` is the project control file. It names the work, points at the source files, saves the questions, and selects the compilation workflow.
131
+ - A workflow package bundles a compilation workflow.
132
+ - `workflow.json` defines the method.
133
+ - `workflow.schema.json` defines the output contract, or context interface, the compiler must build.
134
+ - `Interf Compiler` is the local runtime. It runs the compilation workflow, your agent runs each stage, and the portable context lands next to the source files.
135
+ - The portable context is the local folder built for your agents. Technically, that folder is the compiled context.
100
136
 
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.
137
+ ## interf.json
138
+
139
+ `interf.json` is the main config file in the project root. Each entry describes one piece of agent work: the source path, the saved questions, the compilation workflow that prepares the context, and optional defaults.
140
+
141
+ ```text
142
+ {
143
+ "datasets": [
144
+ {
145
+ "name": "bristol-office-analysis",
146
+ "path": "./bristol-office-analysis",
147
+ "about": "Read the report and answer the saved questions.",
148
+ "workflow": "interf",
149
+ "checks": [
150
+ { "question": "...", "answer": "..." }
151
+ ]
152
+ }
153
+ ]
154
+ }
155
+ ```
156
+
157
+ The `workflow` field is the key choice per work. Set it to `interf` for the built-in workflow, or to a compilation workflow you have authored. A different compilation workflow is a different method and a different output. Same files, different portable context.
158
+
159
+ ## Questions
160
+
161
+ In the flow, they look like plain questions. In `interf.json`, they live under `checks[]`.
102
162
 
103
163
  They should be small, verifiable facts you already know from the files:
104
164
 
@@ -111,7 +171,7 @@ Interf proposes an initial set from the files and the work description. You conf
111
171
  A maintained public test example in this repo stores them like this:
112
172
 
113
173
  <!-- PUBLIC_TEST_CHECKS:START -->
114
- ```jsonc
174
+ ```text
115
175
  {
116
176
  "datasets": [
117
177
  {
@@ -134,34 +194,28 @@ A maintained public test example in this repo stores them like this:
134
194
  ```
135
195
  <!-- PUBLIC_TEST_CHECKS:END -->
136
196
 
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.
197
+ ## What Interf Is Not
140
198
 
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
144
-
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.
199
+ - Not a second brain or memory product. One local folder per piece of agent work; nothing global.
154
200
  - Not a vector store or RAG server. The portable context is plain files.
155
201
  - Not a hosted context layer. Interf runs locally and `interf/` is yours.
156
202
  - Not an agent harness. Interf prepares the folder; your existing agent reads it.
157
203
  - Not a public leaderboard. Every score comes from your files, your questions, and your agent.
158
204
 
205
+ ## Useful Commands
206
+
207
+ - `interf` or `interf init` — open the wizard and save the first setup
208
+ - `interf compile` — build portable context for your agents
209
+ - `interf test` — compare source files and portable context on the same questions
210
+ - `interf create workflow` — draft a reusable workflow package
211
+ - `interf doctor --live` — verify the local executor
212
+
159
213
  ## Docs
160
214
 
161
215
  - [src/packages/README.md](./src/packages/README.md) — system map
162
216
  - [src/packages/compiler/PACKAGE.md](./src/packages/compiler/PACKAGE.md) — compiler primitives and runtime contract
163
217
  - [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
218
+ - [src/packages/workflow-authoring/PACKAGE.md](./src/packages/workflow-authoring/PACKAGE.md) — workflow authoring and workflow improvement
165
219
 
166
220
  Contributors: see [CONTRIBUTING.md](./CONTRIBUTING.md).
167
221
 
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.9",
4
+ "description": "Local, open-source context compiler for agent work. Build portable context from your files with a compilation workflow you define. Check on your own questions.",
5
5
  "type": "module",
6
6
  "bin": {
7
7
  "interf": "dist/bin.js"