webcontextinterface

KO | EN

gitlite — search

#javascript #python #llm #go #machine-learning #rust #docker #windows #awesome #kubernetes #awesome-list #ios #mcp #open-source

webcontextinterface

(★ 22)

A lightweight open standard that augments HTML with semantic metadata, turning standard web pages into highly optimized context for AI agents.

webcontextinterface 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

**WCI (Web Context Interface)** is a three-layer open standard that augments standard HTML with structured semantic metadata, compresses it into agent-optimised context, and provides a typed action protocol — shipped as **compact modular layers** (~2–12 KB minified each).

| | |
|---|---|
| 🏷️ | Semantic HTML annotations (`data-wci-*`) |
| ⚗️ | Token-efficient distillation for LLM context |
| ⚡ | Typed browser actions via `WciBridge` |
| 🛡️ | Site-wide agent policy (`wci.txt` / `wci.json` / `wci.md`) |
| 🔌 | [MCP server](./packages/mcp) — use WCI from Claude, Cursor, or any agent runtime |
| 🩺 | [Validator + CLI](./packages/cli) — `wci validate`, `wci distil`, `wci stats`, `wci init` |
| ⚛️ | [React bindings](./packages/react) — typed annotations with scope inheritance |
| 🤖 | [Annotator](./packages/annotator) — works on sites that never adopted WCI |
| 🧪 | 50-scenario grounding benchmark (see below) + [Zenodo dataset](https://doi.org/10.5281/zenodo.20434088) |

![WCI architecture: data-wci-* markup, distiller, LLM context, WciBridge actions, and site context files](https://raw.githubusercontent.com/amirrezaalasti/webcontextinterface/main/assets/architecture.png)

Additionally, three **site root files** give agents site-wide grounding before they touch a single page — analogous to `robots.txt`:

| File | Purpose |
|------|---------|
| `/wci.txt` | Directive file — allow/deny scopes, rate limits, auth |
| `/wci.json` | Structured manifest — task flows, scope descriptors |
| `/wci.md` | Narrative context — injected into LLM system prompt |

---

## 🌐 Documentation website

**Live (Vercel):** [webcontextinterface.vercel.app](https://webcontextinterface.vercel.app/) · [Demo](https://webcontextinterface.vercel.app/demo/)

**Live (GitHub Pages):** [amirrezaalasti.github.io/webcontextinterface](https://amirrezaalasti.github.io/webcontextinterface/) · [Demo](https://amirrezaalasti.github.io/webcontextinterface/demo/)

Static site (VitePress) with guides, API reference, and the interactive demo.

```bash
npm run docs:dev          # docs only → http://localhost:5174
npm run website:build     # docs + demo → docs/.vitepress/dist
npm run website:preview   # preview the full site locally
```

**Deploy:** push to `main` — Vercel rebuilds automatically ([`vercel.json`](./vercel.json)). For GitHub Pages, enable **Settings → Pages → Source: GitHub Actions**, then the [deploy workflow](.github/workflows/deploy-website.yml) runs on each push.

**Full concept & implementation reference:** [`agent.md`](./agent.md) — vision, agentic interface/AX, spec, APIs, and codebase map.

**NotebookLM (shareable overview):** [WCI notebook](https://notebooklm.google.com/notebook/aa9fa965-4a1b-400d-a605-37f0632c2738) — audio summaries, Q&A, and briefings grounded in the paper, specification, and benchmark materials (Google sign-in required).

Markdown sources live in [`docs/`](./docs/). Quick links:

| Guide | Topic |
|-------|--------|
| [🚀 Getting started](./docs/getting-started.md) | Install, annotate, distil, dispatch |
| [🏗️ Architecture](./docs/architecture.md) | Layers and data flow |
| [📋 Specification](./docs/specification.md) | `data-wci-*` and site files |
| [⚗️ Distillation](./docs/distillation.md) | `WciDistiller` |
| [⚡ Action protocol](./docs/action-protocol.md) | `WciBridge` / `ActionResult` |
| [🛡️ Site policy](./docs/site-policy.md) | `wci.txt` and policy engine |
| [🤖 LLM integration](./docs/llm-integration.md) | Closed-loop agent patterns |

---

## 📦 Install

**Monorepo (development):**

```bash
npm install
npm run build
```

**npm packages** (v1.3.0):

```bash
npm install @webcontextinterface/core@^1.3.0
```

Or install layers individually: `spec`, `distiller`, `bridge`, `context`, `validator`, `react`.

Tooling installs separately: `@webcontextinterface/cli` and `@webcontextinterface/mcp`.

---

## 🧩 Packages

| Package | Version | Description |
|---------|---------|-------------|
| [`@webcontextinterface/spec`](./packages/spec) | 1.3.0 | TypeScript types, role enum, `readWciNodeSpec()`, realm-safe DOM guards |
| [`@webcontextinterface/distiller`](./packages/distiller) | 1.3.0 | Pruner, JSON/Markdown serializers, token budgeting, incremental diffs |
| [`@webcontextinterface/bridge`](./packages/bridge) | 1.3.0 | `WciBridge`, policy enforcement, typed `ActionResult` |
| [`@webcontextinterface/context`](./packages/context) | 1.3.0 | `WciContextLoader`, `PolicyEngine`, `wci.txt` parser |
| [`@webcontextinterface/validator`](./packages/validator) | 1.3.0 | Lint markup, `wci.txt`, and `wci.json` |
| [`@webcontextinterface/annotator`](./packages/annotator) | 1.3.0 | Derive `data-wci-*` from unannotated HTML via ARIA and accessible names |
| [`@webcontextinterface/react`](./packages/react) | 1.3.0 | Components and hooks for declarative annotation |
| [`@webcontextinterface/cli`](./packages/cli) | 1.3.0 | `wci validate` / `distil` / `stats` / `init` |
| [`@webcontextinterface/mcp`](./packages/mcp) | 1.3.0 | Model Context Protocol server — 8 tools |
| [`@webcontextinterface/core`](./packages/core) | 1.3.0 | **All-in-one SDK** — re-exports the library layers |

---

## ⚡ Two-minute start

**Use WCI from an agent** — no code, works with Claude Desktop, Claude Code, and Cursor:

```json
{ "mcpServers": { "wci": { "command": "npx", "args": ["-y", "@webcontextinterface/mcp"] } } }
```

**Already have a site? Derive the annotations:**

```bash
npx @webcontextinterface/cli annotate legacy-page.html --out annotated.html
```

WCI is not inert on unannotated pages — the annotator reconstructs the layer from
ARIA roles, accessible names, and form structure, then you edit the descriptions.

**Make your own site agent-ready:**

```bash
npx @webcontextinterface/cli init --dir public --name "Acme" --url https://acme.com
# annotate your markup, then:
npx @webcontextinterface/cli validate dist/**/*.html --strict
npx @webcontextinterface/cli stats dist/index.html
```

**Keep it honest in CI:**

```yaml
- uses: amirrezaalasti/webcontextinterface/.github/actions/wci-validate@main
  with:
    files: 'dist/**/*.html public/wci.txt public/wci.json'
    strict: 'true'
```

---

## 🚀 Quick start

### 1. Annotate your HTML

```html
<section
  data-wci-role="landmark"
  data-wci-id="registration-form"
  data-wci-desc="New user registration — capture email, password, accept terms">

<button
    data-wci-id="submit-btn"
    data-wci-role="action"
    data-wci-desc="Submit registration — creates the account"
    data-wci-action="click"
    data-wci-precondition="All required fields must be valid"
    data-wci-scope="registration-form"
    data-wci-priority="1"
  >Create Account</button>

</section>
```

### 2. Distil

```typescript
import { WciDistiller } from '@webcontextinterface/distiller';

const distiller = new WciDistiller({ format: 'json', scope: 'registration-form' });
const view = distiller.distilJSON(document);
```

### 3. Dispatch actions

```typescript
import { WciBridge } from '@webcontextinterface/bridge';
import { WciContextLoader } from '@webcontextinterface/context';

const ctx = await WciContextLoader.load('https://your-site.com');
const bridge = new WciBridge();
bridge.setPolicy(ctx.policy);
const result = await bridge.fill('email-input', 'user@example.com');
await bridge.click('submit-btn');
```

### 4. Site context

```typescript
const ctx = await WciContextLoader.load('https://your-site.com');
// Policy is enforced on bridge.dispatch when set via bridge.setPolicy(ctx.policy).
// assertScopeAllowed is optional for pre-flight checks on planned scopes:
ctx.policy.assertScopeAllowed('checkout');
```

---

## 🏷️ `data-wci-*` attribute reference

| Attribute | Type | Description |
|-----------|------|-------------|
| `data-wci-id` | string | Stable unique ID |
| `data-wci-role` | enum | `action` · `form` · `display` · `nav` · `status` · `landmark` |
| `data-wci-desc` | string | LLM-optimised description |
| `data-wci-action` | enum | `click` · `fill` · `select` · `check` · `upload` · `submit` · `navigate` |
| `data-wci-state` | JSON | Current observable state snapshot |
| `data-wci-precondition` | string | Natural language guard condition |
| `data-wci-required` | boolean | Must be satisfied before form submission |
| `data-wci-options` | JSON array | Choices for select/radio groups |
| `data-wci-emit` | string | Custom DOM event fired after interaction |
| `data-wci-scope` | string | Parent landmark scope ID |
| `data-wci-hidden` | boolean | Prune this node from distilled output |
| `data-wci-priority` | 1–5 | Importance ranking (1 = primary CTA) |

See [Specification](./docs/specification.md) for details.

---

## 🔧 Development

```bash
npm install          # install workspaces
npm run build        # build all packages (tsup → dist/)
npm run lint         # TypeScript check
npm run demo         # interactive demo at http://localhost:5173
npm run docs:dev         # documentation at http://localhost:5174
npm run website:build  # full site (docs + demo) for deployment
```

### Repository layout

```
WIA_framework/
├── docs/                 # Full documentation
├── packages/
│   ├── spec/
│   ├── distiller/
│   ├── bridge/
│   ├── context/
│   └── core/             # Umbrella SDK
├── demo/
├── examples/
└── paper/                # Research paper (LaTeX)
```

---

## 🧪 Benchmark

**Official evaluation dataset (Zenodo):** [10.5281/zenodo.20434088](https://doi.org/10.5281/zenodo.20434088) — [Evaluation Dataset for WCI](https://zenodo.org/records/20434088) (CC BY 4.0). Download [`scenarios.zip`](https://zenodo.org/records/20434088/files/scenarios.zip?download=1) for all **50 single-shot grounding scenarios** with five representations each (raw HTML, DOM outline, interactive candidates, WCI full, WCI grounding).

The same scenario tree ships in-repo under [`demo/scenarios/`](./demo/scenarios/) — **5 handmade** scenarios (flight booking, banking, checkout, dashboard, social media) plus **45 synthetic** layouts. The published harness scores **multi-step task grounding** (`meta.tasks.multiStep`, primary task) across those five context formats via OpenRouter.

- **Methodology (public summary):** [`docs/benchmark.md`](./docs/benchmark.md)
- **Commands, comparison tables, and analysis:** [`evals/README.md`](./evals/README.md)
- **Archived run artifacts:** [`demo/public/README.md`](./demo/public/README.md) (`eval-results-gpt5nano.json`, `eval-multistep-report-gemini35flash.json`, …)

```bash
npm run eval:verify
npm run eval:multistep -- --models=gpt5Nano --scenarios=flight-booking,banking
npm run eval:merge-leaderboard   # update demo/public/eval-results-all.json from multistep reports
npm run demo                     # live leaderboard on the website
```

---

## 📝 Citation

If you use WCI in research or publications, please cite:

**Amirreza Alasti** — [amirrezaalasti@gmail.com](mailto:amirrezaalasti@gmail.com)

```bibtex
@software{Alasti_WCI_Web_Context_2026,
  author = {Alasti, Amirreza and Ghandeharioun, Niloufar and Karras, Oliver},
  license = {MIT},
  month = may,
  title = {{WCI: Web Context Interface}},
  url = {https://github.com/amirrezaalasti/webcontextinterface},
  version = {1.2.0},
  year = {2026},
  note = {Contact: amirrezaalasti@gmail.com}
}
```

**Evaluation dataset:**

```bibtex
@dataset{wci_eval_dataset_2026,
  author       = {Alasti, Amirreza},
  title        = {Evaluation Dataset for WCI: The Web Context Interface for Agentic Web Automation},
  year         = {2026},
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.20434088},
  url          = {https://doi.org/10.5281/zenodo.20434088}
}
```

A machine-readable citation file is also provided in [`CITATION.cff`](./CITATION.cff).

---

## 🤝 Contributing

Contributions are welcome! Please read our [Contributing Guidelines](./CONTRIBUTING.md) to learn about our branch naming conventions, development setup, and Conventional Commit principles.

---

## ⚖️ License

MIT — Open Standard. See [LICENSE](./LICENSE).

webcontextinterface

webcontextinterface 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

webcontextinterface

webcontextinterface 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README