Skip to content

Commit 7369ebe

Browse files
darks0ldarks0l
committed
feat: context-kernel v0.1.0 - initial release
0 parents  commit 7369ebe

27 files changed

Lines changed: 2943 additions & 0 deletions

‎.github/workflows/ci.yml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
8+
jobs:
9+
build-test:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v4
13+
- uses: actions/setup-node@v4
14+
with:
15+
node-version: 20
16+
cache: npm
17+
- run: npm ci
18+
- run: npm run lint
19+
- run: npm run test
20+
- run: npm run build

‎.github/workflows/release.yml‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
name: Release
2+
3+
on:
4+
workflow_dispatch:
5+
push:
6+
tags:
7+
- "v*"
8+
9+
jobs:
10+
publish:
11+
runs-on: ubuntu-latest
12+
permissions:
13+
contents: read
14+
id-token: write
15+
steps:
16+
- uses: actions/checkout@v4
17+
- uses: actions/setup-node@v4
18+
with:
19+
node-version: 20
20+
registry-url: https://registry.npmjs.org
21+
cache: npm
22+
- run: npm ci
23+
- run: npm run build
24+
- run: npm publish --access public
25+
env:
26+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
node_modules
2+
dist
3+
coverage
4+
.vscode
5+
.DS_Store

‎.npmignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
src/
2+
test/
3+
.github/
4+
examples/
5+
*.md
6+
tsconfig.json

‎ARCHITECTURE.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Architecture
2+
3+
Service names used across docs/API:
4+
5+
- `ContextKernel` (orchestrator)
6+
- `RouteEngine` (model route decision)
7+
- `BudgetGuard` (token threshold + compression signal)
8+
- `ContextCompactor` (compression stage hook)
9+
- `PolicyGate` (policy DSL evaluation)
10+
- `MemorySignal` (memory candidate extraction)
11+
- `TraceLedger` (audit events sink)
12+
- `BridgeOpenClaw` (OpenClaw adapter)
13+
- `BridgeHTTP` (generic adapter)
14+
15+
## Design rule
16+
17+
Core is platform-agnostic. Adapters map external envelopes into `KernelInput` and map output actions/events back out.

‎CHANGELOG.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Changelog
2+
3+
## 0.1.0
4+
- Initial Context Kernel MVP
5+
- Core routing + token budget compression trigger
6+
- Policy guards (post-only, quiet-hours, secret guard)
7+
- Policy DSL rules (`action_allowlist`, `quiet_hours`, `secret_regex`)
8+
- Memory candidate extraction contract with confidence/source/writeback hints
9+
- OpenClaw + generic HTTP adapters
10+
- CLI runner
11+
- Test suite + CI/release workflows

‎CODE_OF_CONDUCT.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Code of Conduct
2+
3+
Be respectful, constructive, and professional.
4+
5+
## Expected behavior
6+
7+
- Assume good intent.
8+
- Give actionable feedback.
9+
- Keep discussion focused on code and outcomes.
10+
11+
## Unacceptable behavior
12+
13+
- Harassment or personal attacks
14+
- Discrimination of any kind
15+
- Doxxing or sharing private information
16+
17+
Maintainers may moderate or remove content that violates this policy.

‎CONTRIBUTING.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Contributing
2+
3+
Thanks for contributing to `context-kernel`.
4+
5+
## Development
6+
7+
```bash
8+
npm install
9+
npm run test
10+
npm run build
11+
```
12+
13+
## Pull Requests
14+
15+
- Keep changes scoped and documented.
16+
- Add or update tests for behavior changes.
17+
- Update `CHANGELOG.md` for user-visible changes.
18+
- Ensure CI passes (lint, test, build).
19+
20+
## Commit style
21+
22+
Conventional Commits preferred:
23+
24+
- `feat:`
25+
- `fix:`
26+
- `docs:`
27+
- `refactor:`
28+
- `test:`
29+
- `chore:`

‎README.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# context-kernel (v0.1.0)
2+
3+
Platform-agnostic Context Kernel for agent runtimes.
4+
5+
## What it does
6+
7+
- Classifies input (`text` vs `multimodal`, task type)
8+
- Enforces token budget threshold and compression trigger (>10k by default)
9+
- Routes model choice via configurable route map + model registry
10+
- Applies policy guards (post-only, quiet-hours, no-secret guard)
11+
- Supports rule-based policy DSL (allowlist, quiet-hours, secret regex)
12+
- Extracts memory candidates with confidence/source/writeback hints
13+
- Emits deterministic audit events
14+
- Supports OpenClaw + generic HTTP envelope adapters
15+
16+
## Install
17+
18+
```bash
19+
npm install context-kernel
20+
```
21+
22+
## Quick start (library)
23+
24+
```ts
25+
import { ContextKernel } from "context-kernel";
26+
27+
const kernel = new ContextKernel({
28+
router: {
29+
tokenCompressionThreshold: 10000,
30+
allowPremiumEscalation: true,
31+
modelRegistry: {
32+
local_text: { provider: "ollama", model: "lfm2:latest" },
33+
local_vision: { provider: "ollama", model: "qwen3-vl:latest" },
34+
premium: { provider: "anthropic", model: "claude-sonnet-4-6" }
35+
},
36+
routeMap: {
37+
textDefault: "local_text",
38+
multimodal: "local_vision",
39+
urgent: "premium",
40+
codeHighContext: "premium"
41+
}
42+
},
43+
policy: {
44+
postOnlyMode: false,
45+
rules: [
46+
{
47+
id: "safe-actions",
48+
kind: "action_allowlist",
49+
actions: ["send", "post", "tool_call"]
50+
}
51+
]
52+
}
53+
});
54+
55+
const decision = await kernel.decide({
56+
sessionId: "abc",
57+
timestamp: new Date().toISOString(),
58+
messages: [{ role: "user", content: "Help me refactor this repo" }],
59+
estimatedTokens: 12000
60+
});
61+
```
62+
63+
## Quick start (CLI)
64+
65+
```bash
66+
context-kernel --config ./examples/kernel.config.json --input ./examples/input.json
67+
```
68+
69+
## Adapters
70+
71+
- `context-kernel/adapters/openclaw`
72+
- `context-kernel/adapters/http`
73+
74+
## Presets
75+
76+
- `examples/preset.openclaw.json`
77+
- `examples/preset.generic.json`
78+
79+
## Service naming map
80+
81+
- `ContextKernel`, `RouteEngine`, `BudgetGuard`, `ContextCompactor`
82+
- `PolicyGate`, `MemorySignal`, `TraceLedger`
83+
- `BridgeOpenClaw`, `BridgeHTTP`
84+
85+
## Output contract
86+
87+
Main decision object includes:
88+
89+
- `route`
90+
- `compress`
91+
- `policyVerdicts`
92+
- `memoryCandidates`
93+
- `actions`
94+
95+
Audit events include:
96+
97+
- `started`, `classified`, `guard_blocked`, `routed`, `compressed`, `completed`, `failed`
98+
99+
## Policy DSL
100+
101+
Rule kinds:
102+
103+
- `action_allowlist`
104+
- `quiet_hours`
105+
- `secret_regex`
106+
107+
Each rule has stable `id`, optional `reason`, optional `severity`.
108+
109+
## Memory candidate contract
110+
111+
Each candidate includes:
112+
113+
- `summary`
114+
- `tags`
115+
- `priority`
116+
- `confidence` (`0..1`)
117+
- `source` (`messageIndexes`, extraction strategy)
118+
- optional `writebackHint` (namespace/upsert/ttl)
119+
120+
## Development
121+
122+
```bash
123+
npm install
124+
npm run build
125+
npm test
126+
```
127+
128+
## CI and release
129+
130+
- CI workflow: `.github/workflows/ci.yml`
131+
- Release workflow: `.github/workflows/release.yml`
132+
- Add `NPM_TOKEN` secret in GitHub Actions
133+
- Tag and push: `git tag v0.1.0 && git push origin v0.1.0`

‎RELEASING.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Releasing
2+
3+
## One-time setup
4+
5+
- Create npm token with publish access.
6+
- Add `NPM_TOKEN` secret to GitHub Actions.
7+
8+
## Local preflight
9+
10+
```bash
11+
npm ci
12+
npm run release:check
13+
```
14+
15+
## Version + tag
16+
17+
```bash
18+
npm version patch
19+
git push origin main --follow-tags
20+
```
21+
22+
## Publish flow
23+
24+
- Pushing tag `v*` triggers `.github/workflows/release.yml`
25+
- Workflow builds and publishes to npm.
26+
27+
## Manual fallback
28+
29+
```bash
30+
npm publish --access public
31+
```

0 commit comments

Comments
 (0)