@interf/compiler 0.6.8 → 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 (2) hide show
  1. package/README.md +38 -61
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,15 +1,12 @@
1
1
  # Interf
2
2
 
3
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
4
 
6
- **The files can be right. The agent can still be wrong.**
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
- 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.
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 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
-
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.
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
12
  project-root/
@@ -26,27 +23,10 @@ project-root/
26
23
 
27
24
  The project root is the control plane. Your agent starts from `interf/<work>/` when the source files are not enough.
28
25
 
29
- ## What a Run Looks Like
30
-
31
- A recent public run — one PDF market report, two questions, two agents on the same setup — produced:
32
-
33
- <!-- PUBLIC_BENCHMARK_TABLE:START -->
34
- | Agent | Source files | Portable context |
35
- | --- | --- | --- |
36
- | Codex (GPT-5.4, xhigh) | `2/2` | `2/2` |
37
- | Claude Code (Claude Opus 4.6, max) | `0/2` | `2/2` |
38
- <!-- PUBLIC_BENCHMARK_TABLE:END -->
39
-
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.
41
-
42
- That gives you a readiness signal for the work and a fair comparison on the same files.
43
-
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.
45
-
46
26
  ## Design Choices
47
27
 
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.
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.
50
30
  - `File over app`: the portable context is a local folder next to the source files. Inspect it, diff it, version it.
51
31
  - `Bring your own AI`: use Claude Code, Codex, or another local agent.
52
32
  - `Explicit`: no hidden store, no hidden index. The portable context is plain files on disk.
@@ -63,19 +43,19 @@ Requires Node.js 20+ and a local coding agent such as Claude Code or Codex. Run
63
43
  ## Quick Start
64
44
 
65
45
  1. Run `interf` in the project root.
66
- 2. Pick the source folder for one work.
46
+ 2. Pick the source folder for one piece of agent work.
67
47
  3. Describe what the agent should do with those files.
68
48
  4. Review the suggested questions.
69
- 5. Run `interf test --target raw` to check the source files.
49
+ 5. Run `interf test --target raw` to score the source files.
70
50
  6. Run `interf compile` to build portable context.
71
51
  7. Run `interf test` again to compare source files and portable context on the same questions.
72
52
  8. If the portable context does better, point your agent at `interf/<work>/`.
73
53
 
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.
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.
75
55
 
76
56
  ## Portable Context
77
57
 
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:
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:
79
59
 
80
60
  ```text
81
61
  interf/bristol-office-analysis/
@@ -89,21 +69,19 @@ interf/bristol-office-analysis/
89
69
 
90
70
  The source files stay the source of truth. Interf builds next to them; it does not replace them.
91
71
 
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.
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.
93
73
 
94
74
  ## Workflow Packages
95
75
 
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.
97
-
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.
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.
99
77
 
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.
78
+ Run `interf create workflow` to draft a reusable workflow package.
101
79
 
102
80
  ```text
103
81
  interf/workflows/office-analysis/
104
82
  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
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
107
85
  compile/
108
86
  stages/
109
87
  summarize/ # define your own stages here
@@ -111,55 +89,54 @@ interf/workflows/office-analysis/
111
89
  shape/
112
90
  use/
113
91
  query/ # how your agent reads the portable context
114
- improve/ # how Interf revises this workflow if questions still fail
92
+ improve/ # how Interf revises this compilation workflow if questions still fail
115
93
  ```
116
94
 
117
95
  Think of it as method -> output shape.
118
96
 
119
97
  - `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.
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.
122
100
  - `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
101
+ - `improve/` holds the instructions Interf follows when the first build misses and the compilation workflow itself needs editing.
128
102
 
129
- Every workflow runs on the same three primitives. Interf Compiler enforces the contract. The workflow chooses the method.
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.
130
104
 
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.
105
+ ## What a Run Looks Like
134
106
 
135
- ### Context interface
107
+ A recent public run — one PDF market report, two questions, two agents on the same setup — produced:
136
108
 
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.
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 -->
138
115
 
139
- ### Stage execution
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.
140
117
 
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.
118
+ That gives you a readiness signal for the work and a fair comparison on the same files.
142
119
 
143
- The context interface is the key guarantee. The shape holds on disk, or `interf test` reports the gap on your own questions.
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.
144
121
 
145
122
  ## Self-Improving Workflows
146
123
 
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.
124
+ When the first build still misses questions, Interf edits the workflow package itself and compiles again. Same files, same questions, different preparation.
148
125
 
149
126
  Interf saves every scored run under `interf/tests/<work>/`. You can inspect what changed and why a later build did better.
150
127
 
151
128
  ## How the Pieces Fit
152
129
 
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.
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.
156
133
  - `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.
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.
158
135
  - The portable context is the local folder built for your agents. Technically, that folder is the compiled context.
159
136
 
160
137
  ## interf.json
161
138
 
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.
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.
163
140
 
164
141
  ```text
165
142
  {
@@ -177,7 +154,7 @@ Interf saves every scored run under `interf/tests/<work>/`. You can inspect what
177
154
  }
178
155
  ```
179
156
 
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.
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.
181
158
 
182
159
  ## Questions
183
160
 
@@ -219,7 +196,7 @@ A maintained public test example in this repo stores them like this:
219
196
 
220
197
  ## What Interf Is Not
221
198
 
222
- - Not a second brain or memory product. One local folder per work; nothing global.
199
+ - Not a second brain or memory product. One local folder per piece of agent work; nothing global.
223
200
  - Not a vector store or RAG server. The portable context is plain files.
224
201
  - Not a hosted context layer. Interf runs locally and `interf/` is yours.
225
202
  - Not an agent harness. Interf prepares the folder; your existing agent reads it.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@interf/compiler",
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.",
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"