swadhin / contexa public

zig: add package README with zig fetch install instructions

Swadhin Biswas committed 7 months ago
9f1832f
1 parent 4de19b8
commit 9f1832f
1 file changed
+191 -0
Showing 1 changed file+191-0
ZIG/README.md
▼ZIG/README.md
+191-0
@@ -0,0 +1,191 @@
1
+# contexa
2
+
3
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
4
+[![GitHub](https://img.shields.io/badge/GitHub-swadhinbiswas%2Fcontexa-black.svg?logo=github)](https://github.com/swadhinbiswas/contexa)
5
+
6
+**Git-inspired context management for LLM agents.** COMMIT, BRANCH, MERGE, and CONTEXT operations over a persistent versioned memory workspace.
7
+
8
+Zig implementation of the **contexa** framework.
9
+
10
+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)
11
+
12
+---
13
+
14
+## Installation
15
+
16
+### As a Zig package dependency
17
+
18
+Add to your `build.zig.zon`:
19
+
20
+```zig
21
+.dependencies = .{
22
+ .contexa = .{
23
+ .url = "https://github.com/swadhinbiswas/contexa/archive/refs/tags/v0.1.1.tar.gz",
24
+ .hash = "...", // zig build will tell you the correct hash
25
+ },
26
+},
27
+```
28
+
29
+Then in your `build.zig`:
30
+
31
+```zig
32
+const contexa = b.dependency("contexa", .{
33
+ .target = target,
34
+ .optimize = optimize,
35
+});
36
+exe.root_module.addImport("contexa", contexa.module("contexa"));
37
+```
38
+
39
+---
40
+
41
+## Quick Start
42
+
43
+```zig
44
+const std = @import("std");
45
+const contexa = @import("contexa");
46
+
47
+pub fn main() !void {
48
+ var gpa = std.heap.GeneralPurposeAllocator(.{}){};
49
+ defer _ = gpa.deinit();
50
+ const allocator = gpa.allocator();
51
+
52
+ // 1. Initialize a workspace
53
+ var ws = contexa.Workspace.init(allocator, "/path/to/project");
54
+ try ws.create("Build a REST API service with user auth");
55
+
56
+ // 2. Agent logs its reasoning as it works
57
+ _ = try ws.logOTA(
58
+ "Project directory is empty",
59
+ "Need to scaffold the project structure first",
60
+ "create_files(['main.zig', 'build.zig'])",
61
+ );
62
+
63
+ // 3. Commit a milestone
64
+ const c = try ws.commit("Project scaffold complete", null);
65
+ defer allocator.free(c.commit_id);
66
+
67
+ // 4. Branch to explore an alternative approach
68
+ try ws.branch("auth-jwt", "Explore JWT-based authentication");
69
+ _ = try ws.logOTA("Reading JWT docs", "JWT is stateless", "implementJWT()");
70
+ const c2 = try ws.commit("JWT auth implemented", null);
71
+ defer allocator.free(c2.commit_id);
72
+
73
+ // 5. Merge the successful branch back
74
+ const mc = try ws.merge("auth-jwt", "main");
75
+ defer allocator.free(mc.commit_id);
76
+
77
+ // 6. Retrieve context (K=1: paper default)
78
+ const ctx = try ws.context(null, 1);
79
+ defer ctx.deinit(allocator);
80
+
81
+ std.debug.print("Roadmap:\n{s}\n", .{ctx.main_roadmap});
82
+}
83
+```
84
+
85
+---
86
+
87
+## Core Concepts
88
+
89
+### Workspace
90
+
91
+The `Workspace` struct manages the `.GCC/` directory structure. All operations use the Zig allocator pattern -- the caller is responsible for freeing returned allocations.
92
+
93
+### Data Models
94
+
95
+| Type | Description |
96
+|------|-------------|
97
+| `OTARecord` | Single Observation-Thought-Action cycle with `writeMarkdown()` |
98
+| `CommitRecord` | Milestone checkpoint with `writeMarkdown()` |
99
+| `BranchMetadata` | Branch intent and status with `writeYaml()` |
100
+| `ContextSnapshot` | CONTEXT result with `deinit()` for cleanup |
101
+
102
+### GCC Commands
103
+
104
+| Command | Method | Description |
105
+|---------|--------|-------------|
106
+| *(init)* | `create(roadmap)` | Create `.GCC/` structure with main branch |
107
+| OTA | `logOTA(obs, thought, action)` | Append OTA step to current branch |
108
+| COMMIT | `commit(contribution, prev?)` | Save milestone checkpoint |
109
+| BRANCH | `branch(name, purpose)` | Create isolated workspace |
110
+| MERGE | `merge(branch, target)` | Integrate branch into target |
111
+| CONTEXT | `context(branch?, k)` | Retrieve history (K-commit window) |
112
+
113
+---
114
+
115
+## Memory Management
116
+
117
+This library follows Zig conventions:
118
+
119
+- `Workspace.init()` takes an `Allocator` used for all internal operations
120
+- `CommitRecord.commit_id` returned by `commit()` and `merge()` must be freed by the caller
121
+- `ContextSnapshot` returned by `context()` owns `main_roadmap`, `ota_log`, and `commit_history` -- call `ctx.deinit(allocator)` when done
122
+- Path helpers allocate and must be freed with `defer allocator.free(path)`
123
+
124
+---
125
+
126
+## Directory Structure
127
+
128
+```
129
+your-project/
130
+ .GCC/
131
+ main.md # Global roadmap
132
+ branches/
133
+ main/
134
+ log.md # Continuous OTA trace
135
+ commit.md # Milestone-level summaries
136
+ metadata.yaml # Branch intent & status
137
+ feature-branch/
138
+ log.md
139
+ commit.md
140
+ metadata.yaml
141
+```
142
+
143
+All data is stored as **human-readable Markdown and YAML**.
144
+
145
+---
146
+
147
+## Building and Testing
148
+
149
+```bash
150
+# Build the library
151
+zig build
152
+
153
+# Run unit tests
154
+zig build test
155
+```
156
+
157
+5 tests cover workspace creation, OTA logging, commits, branching, and context retrieval.
158
+
159
+---
160
+
161
+## Requirements
162
+
163
+- **Zig** >= 0.14.0
164
+- No external dependencies (standard library only)
165
+
166
+---
167
+
168
+## License
169
+
170
+MIT License. See [LICENSE](LICENSE) for details.
171
+
172
+---
173
+
174
+## Citation
175
+
176
+```bibtex
177
+@article{wu2025gcc,
178
+ title={Git Context Controller: Manage the Context of LLM-based Agents like Git},
179
+ author={Wu, Junde and others},
180
+ journal={arXiv preprint arXiv:2508.00031},
181
+ year={2025}
182
+}
183
+```
184
+
185
+---
186
+
187
+## Links
188
+
189
+- [GitHub Repository](https://github.com/swadhinbiswas/contexa)
190
+- [Original Paper](https://arxiv.org/abs/2508.00031)
191
+- [Author: Swadhin Biswas](https://github.com/swadhinbiswas)
0
192