npm package: @interf/compiler
Description: Knowledge compiler that prepares local folders for agent use and lets you test the result on your evals.
Latest version: 0.2.2

# Interf

Interf Knowledge Compiler uses local agents such as Claude Code and Codex to run a data-processing workflow over your files.

It creates a workspace with notes and navigation so the agent can see what is in the folder and what to retrieve.

Then you test that workspace on your evals.

- your files stay on your machine
- you choose the local agent
- you decide what must be true

Agents start missing things when a task spans PDFs, charts, and several files in one folder. That usually shows up when the job depends on:

- reading reports and filings
- extracting a number from a chart
- understanding what is inside a folder before doing work
- pulling context together across several files
- checking the raw source when the answer has to be exact

The workspace exists so the agent does not have to rediscover the folder from scratch on every run.

The point is proof on your data, not generic AI claims.

The simplest way to use Interf is to compare the same task before and after compilation:

- run the task on the raw folder
- compile the folder with Interf
- run the same task again from the workspace
- if you want a recorded pass/fail result, add evals and run `interf benchmark`

## Quick Start

Requirements:

- Node.js 20+
- a local coding agent: Claude Code or Codex

Install and check setup:

```bash
npm install -g @interf/compiler
interf doctor
```

Then run Interf in any folder:

```bash
cd ~/my-folder
interf init
interf compile
interf benchmark
```

That is the whole first loop:

- point Interf at a folder you already have
- let `interf init` write the first evals in `interf.config.json`
- compile the workspace
- ask the agent to use it
- run `interf benchmark` to compare raw vs compiled

`interf init` chooses your local agent, can draft `interf.config.json` if it is missing, and can attach the current folder right away. It does not move or replace your files.

Fastest sample loop:

```bash
cp -r examples/benchmark-demo /tmp/interf-demo
cd /tmp/interf-demo
interf init
interf compile
interf benchmark
```

If you want a task-specific workspace for one job, add an interface:

```bash
interf create interface
interf compile
interf benchmark
```

## Start With One Small Eval

`interf.config.json` is where you write what must be true.

If the file is missing, `interf init` can draft it with you before the first compile.

Use it for:

- top-level `evals` for the main folder
- `interfaces[].evals` for task-specific checks

Example shape:

Top-level `evals` are for the main folder. Each entry in `interfaces` adds evals for one dedicated job.

```json
{
  "evals": [
    {
      "question": "What was Bristol annual take-up in 2018, in millions of square feet?",
      "answer": "About 0.5 million square feet. Accept answers between 0.3 and 0.6 if they clearly refer to Bristol annual take-up in 2018."
    }
  ],
  "interfaces": [
    {
      "name": "market-briefing",
      "about": "Prepare a short briefing from the office market report.",
      "evals": [
        {
          "question": "What was Bristol availability in 2018, in millions of square feet?",
          "answer": "About 0.6 million square feet. Accept answers between 0.5 and 0.7 if they clearly refer to Bristol availability in 2018."
        },
        {
          "question": "Did Bristol annual take-up rise or fall between 2016 and 2018?",
          "answer": "It fell. The chart shows roughly 0.7 to 0.8 million square feet in 2016 and about 0.5 million square feet in 2018."
        }
      ]
    }
  ]
}
```

Good first evals are small and practical:

- one exact number from a chart, table, or filing
- one short statement that should be true or false
- one simple comparison across years, files, or sections

Then run:

```bash
interf compile
interf benchmark
```

If the benchmark does not show an improvement over raw files, keep iterating or move to the experiment loop described below.

## Compare Three Things

Compare:

1. the raw folder
2. the workspace
3. an interface for one specific job

`interf benchmark` is how you compare those on the same evals.

That gives you one clear question:

- is the raw folder enough?
- does the workspace retrieve better?
- does a dedicated interface do better than both?

## What `interf compile` Actually Does

`interf compile` runs a workflow over your folder.

That workflow is the compilation pipeline:

- read the files
- write processed notes and navigation files
- build the workspace your agent can use
- optionally build an interface for one specific job

The default workflow is built in. If you want a different method, you can define your own workflow package and benchmark it on the same folder.

## Experiment Loop

Interf Knowledge Compiler also supports an experiment loop above compile + benchmark.

It runs controlled experiments against the same folder and the same evals. Each attempt reruns the compilation workflow, reruns the benchmark, and records what changed. It stops when:

- the evals pass
- or the experiment budget is exhausted

In practice, that means:

- `retry_policy.max_attempts_per_profile` controls how many experiment attempts each compile profile gets
- stronger diagnostic profiles can be used only after the default ones fail
- the loop is still judged on the same eval truth from your folder
- failure summaries can be captured between attempts for diagnosis

Today that advanced path is configured through eval packs and explained in the deeper docs. The workflow is the part you change. The experiment loop is the controller that runs those experiments against the same evals with a fixed attempt budget.

Use the simple loop first. Use the experiment loop when you want to test workflow or profile changes against the same evals until one passes or the attempt budget runs out.

## Use It With Your Agent

If you already work through Claude Code, Codex, OpenClaw, or Hermes, the agent can run this loop for you.

Paste something like this into Claude Code, Codex, OpenClaw, or Hermes:

```text
Install @interf/compiler, run `interf init` in this folder, and use the local agent executor.

If `interf.config.json` is missing, draft evals for what must be true for this task and ask me to confirm them.

Then run `interf compile` and `interf benchmark`.

Tell me whether the processed workspace beat raw files, and only recommend it if it did.
```

That is the basic loop:

- the user or agent defines what must be true
- Interf prepares processed data for retrieval
- the benchmark shows whether that helped

## What Gets Created

After compile, Interf writes into `./interf/` beside your source files.

- `interf/<name>/` is the shared workspace over the folder
- `interf/<name>/interfaces/<name>/` is a task-specific workspace for one job
- `interf/benchmarks/runs/...` stores saved benchmark runs

Inside those workspaces you will see things like:

- summaries of source files
- navigation notes and entrypoints for agents
- task-specific outputs for one interface
- benchmark artifacts you can inspect later

In the CLI, the main Interf workspace is called a **knowledge base**. A task-specific workspace inside it is called an **interface**.

## When To Create An Interface

Start with one workspace.

Create an interface when your agent needs outputs shaped for one specific job, for example:

- weekly briefing
- diligence on a deal room
- extracting chart values from research PDFs
- a focused research assistant for one question set

If that workspace is enough for the job, you do not need an interface yet.

## Custom Workflows

Interf ships with a default workflow.

If you want to change how compilation happens on your data, this is the part you customize:

```bash
interf create workflow
interf verify workflow --path <path>
```

Then benchmark that workflow on the same folder and the same evals.

Workflow package docs live in [docs/workflow-spec.md](./docs/workflow-spec.md).

## Core Commands

- `interf init` = choose your local executor and optionally attach the current folder
- `interf create knowledge-base` = create the shared processed workspace for this folder
- `interf create interface` = create a task-specific workspace on top
- `interf create workflow` = create a reusable local workflow package
- `interf compile` = build the current workspace
- `interf benchmark` = compare raw files vs processed workspaces on your evals
- `interf doctor` = check local executor setup
- `interf verify <check>` = run deterministic checks on major workflow steps
- `interf reset <scope>` = remove generated state while keeping source files

## More Docs

- [docs/workflow-spec.md](./docs/workflow-spec.md) for custom workflow packages
- [docs/runtime-contract.md](./docs/runtime-contract.md) for the exact on-disk contract
- [docs/architecture.md](./docs/architecture.md) for the deeper system model
- [docs/eval-loop.md](./docs/eval-loop.md) for the advanced benchmark and experiment loop

Maintainers should use [CONTRIBUTING.md](./CONTRIBUTING.md) for test and release gates.

## License

Code is licensed under Apache 2.0. The `Interf` name and branding are reserved; see [TRADEMARKS.md](./TRADEMARKS.md).