swadhin / contexa public

js: add package README with npm install instructions

Swadhin Biswas committed 7 months ago
fab3807
1 parent d323ef0
commit fab3807
1 file changed
+267 -0
Showing 1 changed file+267-0
JS/README.md
▼JS/README.md
+267-0
@@ -0,0 +1,267 @@
1
+# contexa
2
+
3
+[![npm version](https://img.shields.io/npm/v/contexa.svg)](https://www.npmjs.com/package/contexa)
4
+[![Node.js 18+](https://img.shields.io/badge/node-18%2B-blue.svg)](https://nodejs.org/)
5
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
6
+[![GitHub](https://img.shields.io/badge/GitHub-swadhinbiswas%2Fcontexa-black.svg?logo=github)](https://github.com/swadhinbiswas/contexa)
7
+
8
+**Git-inspired context management for LLM agents.** COMMIT, BRANCH, MERGE, and CONTEXT operations over a persistent versioned memory workspace.
9
+
10
+TypeScript/JavaScript implementation of the **contexa** framework.
11
+
12
+Based on: [arXiv:2508.00031](https://arxiv.org/abs/2508.00031) -- *"Git Context Controller: Manage the Context of LLM-based Agents like Git"* (Junde Wu et al., 2025)
13
+
14
+---
15
+
16
+## Installation
17
+
18
+```bash
19
+npm install contexa
20
+```
21
+
22
+Or with yarn/pnpm:
23
+
24
+```bash
25
+yarn add contexa
26
+pnpm add contexa
27
+```
28
+
29
+---
30
+
31
+## Quick Start
32
+
33
+```typescript
34
+import { GCCWorkspace } from "contexa";
35
+
36
+// 1. Initialize a workspace
37
+const ws = new GCCWorkspace("/path/to/project");
38
+ws.init("Build a REST API service with user auth");
39
+
40
+// 2. Agent logs its reasoning as it works
41
+ws.logOTA(
42
+ "Project directory is empty",
43
+ "Need to scaffold the project structure first",
44
+ "create_files(['main.ts', 'package.json', 'models.ts'])"
45
+);
46
+
47
+// 3. Commit a milestone (compresses OTA history)
48
+ws.commit("Project scaffold and User model complete");
49
+
50
+// 4. Branch to explore an alternative approach
51
+ws.branch("auth-jwt", "Explore JWT-based authentication");
52
+ws.logOTA("Reading JWT docs", "JWT is stateless, good for APIs", "implementJWT()");
53
+ws.commit("JWT auth middleware implemented");
54
+
55
+// 5. Merge the successful branch back
56
+ws.merge("auth-jwt");
57
+
58
+// 6. Retrieve context for the agent's next step
59
+const ctx = ws.context(undefined, 1); // K=1: paper default
60
+console.log(ctx.summary());
61
+```
62
+
63
+---
64
+
65
+## Core Concepts
66
+
67
+### OTA Logging (Observation-Thought-Action)
68
+
69
+Every reasoning step is an OTA cycle, logged continuously in `log.md`:
70
+
71
+```typescript
72
+const rec = ws.logOTA(
73
+ "API returns 500 error on /users endpoint",
74
+ "The database connection might not be initialized",
75
+ "checkDbConnection()"
76
+);
77
+console.log(rec.step); // 1 (auto-incremented)
78
+console.log(rec.timestamp); // 2025-03-04T12:00:00.000Z
79
+```
80
+
81
+### COMMIT -- Save Milestones
82
+
83
+```typescript
84
+const commit = ws.commit(
85
+ "Fixed database connection and /users endpoint returns 200",
86
+ undefined, // previous summary auto-populated
87
+ "Database layer stable, move on" // optional roadmap update
88
+);
89
+console.log(commit.commitId); // "a3f2b1c4" (8-char hex)
90
+console.log(commit.branchName); // "main"
91
+```
92
+
93
+### BRANCH -- Explore Alternatives
94
+
95
+```typescript
96
+ws.branch("redis-cache", "Try Redis caching instead of in-memory");
97
+ws.logOTA("Redis docs reviewed", "Need redis package", "npmInstall('redis')");
98
+ws.commit("Redis caching layer implemented");
99
+
100
+console.log(ws.listBranches()); // ['main', 'redis-cache']
101
+console.log(ws.currentBranch); // 'redis-cache'
102
+```
103
+
104
+### MERGE -- Integrate Results
105
+
106
+```typescript
107
+const mergeCommit = ws.merge("redis-cache", undefined, "main");
108
+// - Appends branch OTA trace to main's log
109
+// - Creates a merge commit on main
110
+// - Marks branch as "merged" in metadata
111
+console.log(ws.currentBranch); // 'main'
112
+```
113
+
114
+### CONTEXT -- Retrieve History
115
+
116
+```typescript
117
+// K=1: only the most recent commit (paper's recommended default)
118
+const ctx = ws.context(undefined, 1);
119
+
120
+console.log(ctx.branchName); // "main"
121
+console.log(ctx.mainRoadmap); // Global project roadmap
122
+console.log(ctx.commits); // Last K CommitRecord objects
123
+console.log(ctx.otaRecords); // All OTA records on the branch
124
+console.log(ctx.metadata); // BranchMetadata object
125
+
126
+// Formatted markdown summary ready for LLM prompt injection
127
+const promptContext = ctx.summary();
128
+```
129
+
130
+---
131
+
132
+## API Reference
133
+
134
+### `GCCWorkspace`
135
+
136
+| Method | Parameters | Returns | Description |
137
+|--------|-----------|---------|-------------|
138
+| `constructor` | `projectRoot: string` | -- | Set the project root directory |
139
+| `init` | `projectRoadmap?: string` | `void` | Create `.GCC/` structure with main branch |
140
+| `load` | -- | `void` | Load an existing workspace |
141
+| `logOTA` | `observation, thought, action` | `OTARecord` | Append OTA step to current branch |
142
+| `commit` | `contribution, previousSummary?, updateRoadmap?` | `CommitRecord` | Create milestone checkpoint |
143
+| `branch` | `name, purpose` | `void` | Create and switch to new branch |
144
+| `merge` | `branchName, summary?, target?` | `CommitRecord` | Merge branch into target |
145
+| `context` | `branch?, k?` | `ContextResult` | Retrieve historical context |
146
+| `switchBranch` | `name` | `void` | Switch active branch |
147
+| `listBranches` | -- | `string[]` | List all branch names |
148
+| `currentBranch` | *(getter)* | `string` | Get current active branch name |
149
+
150
+---
151
+
152
+## Type Definitions
153
+
154
+```typescript
155
+interface OTARecord {
156
+ step: number;
157
+ timestamp: string;
158
+ observation: string;
159
+ thought: string;
160
+ action: string;
161
+}
162
+
163
+interface CommitRecord {
164
+ commitId: string;
165
+ branchName: string;
166
+ branchPurpose: string;
167
+ previousProgressSummary: string;
168
+ thisCommitContribution: string;
169
+ timestamp: string;
170
+}
171
+
172
+interface BranchMetadata {
173
+ name: string;
174
+ purpose: string;
175
+ createdFrom: string;
176
+ createdAt: string;
177
+ status: "active" | "merged" | "abandoned";
178
+ mergedInto?: string;
179
+ mergedAt?: string;
180
+}
181
+
182
+interface ContextResult {
183
+ branchName: string;
184
+ k: number;
185
+ commits: CommitRecord[];
186
+ otaRecords: OTARecord[];
187
+ mainRoadmap: string;
188
+ metadata?: BranchMetadata;
189
+ summary(): string;
190
+}
191
+```
192
+
193
+---
194
+
195
+## Directory Structure
196
+
197
+```
198
+your-project/
199
+ .GCC/
200
+ main.md # Global roadmap
201
+ branches/
202
+ main/
203
+ log.md # Continuous OTA trace
204
+ commit.md # Milestone-level summaries
205
+ metadata.yaml # Branch intent & status
206
+ feature-branch/
207
+ log.md
208
+ commit.md
209
+ metadata.yaml
210
+```
211
+
212
+All data is stored as **human-readable Markdown and YAML**.
213
+
214
+---
215
+
216
+## Running Tests
217
+
218
+```bash
219
+git clone https://github.com/swadhinbiswas/contexa.git
220
+cd contexa/JS
221
+npm install
222
+npm test
223
+```
224
+
225
+---
226
+
227
+## Building
228
+
229
+```bash
230
+npm run build
231
+# Outputs dist/index.js (CJS), dist/index.mjs (ESM), dist/index.d.ts (types)
232
+```
233
+
234
+---
235
+
236
+## Requirements
237
+
238
+- **Node.js** >= 18
239
+- **js-yaml** >= 4.1.0
240
+
241
+---
242
+
243
+## License
244
+
245
+MIT License. See [LICENSE](LICENSE) for details.
246
+
247
+---
248
+
249
+## Citation
250
+
251
+```bibtex
252
+@article{wu2025gcc,
253
+ title={Git Context Controller: Manage the Context of LLM-based Agents like Git},
254
+ author={Wu, Junde and others},
255
+ journal={arXiv preprint arXiv:2508.00031},
256
+ year={2025}
257
+}
258
+```
259
+
260
+---
261
+
262
+## Links
263
+
264
+- [GitHub Repository](https://github.com/swadhinbiswas/contexa)
265
+- [npm Package](https://www.npmjs.com/package/contexa)
266
+- [Original Paper](https://arxiv.org/abs/2508.00031)
267
+- [Author: Swadhin Biswas](https://github.com/swadhinbiswas)
0
268