swadhin / contexa public

go: add package README with go get instructions

Swadhin Biswas committed 7 months ago
301f4dd
1 parent fee4079
commit 301f4dd
1 file changed
+218 -0
Showing 1 changed file+218-0
GO/README.md
▼GO/README.md
+218-0
@@ -0,0 +1,218 @@
1
+# contexa
2
+
3
+[![Go Reference](https://pkg.go.dev/badge/github.com/swadhinbiswas/contexa.svg)](https://pkg.go.dev/github.com/swadhinbiswas/contexa)
4
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
5
+[![GitHub](https://img.shields.io/badge/GitHub-swadhinbiswas%2Fcontexa-black.svg?logo=github)](https://github.com/swadhinbiswas/contexa)
6
+
7
+**Git-inspired context management for LLM agents.** COMMIT, BRANCH, MERGE, and CONTEXT operations over a persistent versioned memory workspace.
8
+
9
+Go implementation of the **contexa** framework.
10
+
11
+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)
12
+
13
+---
14
+
15
+## Installation
16
+
17
+```bash
18
+go get github.com/swadhinbiswas/contexa/cortexa
19
+```
20
+
21
+---
22
+
23
+## Quick Start
24
+
25
+```go
26
+package main
27
+
28
+import (
29
+ "fmt"
30
+ "github.com/swadhinbiswas/contexa/cortexa"
31
+)
32
+
33
+func main() {
34
+ ws := cortexa.New("/path/to/project")
35
+ if err := ws.Init("Build a REST API service with user auth"); err != nil {
36
+ panic(err)
37
+ }
38
+
39
+ ws.LogOTA(
40
+ "Project directory is empty",
41
+ "Need to scaffold the project structure first",
42
+ "create_files(['main.go', 'go.mod', 'models.go'])",
43
+ )
44
+
45
+ ws.Commit("Project scaffold and User model complete", nil, nil)
46
+
47
+ ws.Branch("auth-jwt", "Explore JWT-based authentication")
48
+ ws.LogOTA("Reading JWT docs", "JWT is stateless", "implementJWT()")
49
+ ws.Commit("JWT auth middleware implemented", nil, nil)
50
+
51
+ ws.Merge("auth-jwt", nil, "main")
52
+
53
+ ctx, _ := ws.Context(nil, 1) // K=1: paper default
54
+ fmt.Println(ctx.Summary())
55
+}
56
+```
57
+
58
+---
59
+
60
+## Core Concepts
61
+
62
+### OTA Logging (Observation-Thought-Action)
63
+
64
+```go
65
+rec, err := ws.LogOTA(
66
+ "API returns 500 error on /users endpoint",
67
+ "The database connection might not be initialized",
68
+ "checkDbConnection()",
69
+)
70
+fmt.Println(rec.Step) // 1 (auto-incremented)
71
+fmt.Println(rec.Timestamp) // RFC3339 timestamp
72
+```
73
+
74
+### COMMIT -- Save Milestones
75
+
76
+```go
77
+commit, err := ws.Commit(
78
+ "Fixed database connection, /users returns 200",
79
+ nil, // previous summary auto-populated from last commit
80
+ nil, // optional roadmap update
81
+)
82
+fmt.Println(commit.CommitID) // "a3f2b1c4" (8-char hex)
83
+fmt.Println(commit.BranchName) // "main"
84
+```
85
+
86
+### BRANCH -- Explore Alternatives
87
+
88
+```go
89
+ws.Branch("redis-cache", "Try Redis caching instead of in-memory")
90
+ws.LogOTA("Redis docs reviewed", "Need redis package", "goGet('redis')")
91
+ws.Commit("Redis caching layer implemented", nil, nil)
92
+
93
+fmt.Println(ws.CurrentBranch()) // "redis-cache"
94
+branches, _ := ws.ListBranches()
95
+fmt.Println(branches) // ["main", "redis-cache"]
96
+```
97
+
98
+### MERGE -- Integrate Results
99
+
100
+```go
101
+mergeCommit, err := ws.Merge("redis-cache", nil, "main")
102
+// Appends branch OTA trace to main's log
103
+// Creates a merge commit on main
104
+// Marks branch as "merged" in metadata
105
+fmt.Println(ws.CurrentBranch()) // "main"
106
+```
107
+
108
+### CONTEXT -- Retrieve History
109
+
110
+```go
111
+ctx, err := ws.Context(nil, 1) // K=1: paper default
112
+
113
+fmt.Println(ctx.BranchName) // "main"
114
+fmt.Println(ctx.MainRoadmap) // Global project roadmap
115
+fmt.Println(ctx.Commits) // Last K CommitRecords
116
+fmt.Println(ctx.OTARecords) // All OTA records
117
+fmt.Println(ctx.Metadata) // *BranchMetadata
118
+
119
+// Formatted markdown summary for LLM prompt injection
120
+fmt.Println(ctx.Summary())
121
+```
122
+
123
+---
124
+
125
+## API Overview
126
+
127
+### `Workspace`
128
+
129
+| Method | Signature | Description |
130
+|--------|-----------|-------------|
131
+| `New` | `(projectRoot string) *Workspace` | Create workspace handle |
132
+| `Init` | `(roadmap string) error` | Create `.GCC/` structure |
133
+| `Load` | `() error` | Load existing workspace |
134
+| `LogOTA` | `(obs, thought, action string) (OTARecord, error)` | Append OTA step |
135
+| `Commit` | `(contribution string, prev, roadmap *string) (CommitRecord, error)` | Checkpoint milestone |
136
+| `Branch` | `(name, purpose string) error` | Create and switch branch |
137
+| `Merge` | `(branch string, summary *string, target string) (CommitRecord, error)` | Merge branch |
138
+| `Context` | `(branch *string, k int) (ContextResult, error)` | Retrieve context |
139
+| `SwitchBranch` | `(name string) error` | Switch active branch |
140
+| `ListBranches` | `() ([]string, error)` | List all branches |
141
+| `CurrentBranch` | `() string` | Get current branch |
142
+
143
+### Data Models
144
+
145
+| Struct | Description |
146
+|--------|-------------|
147
+| `OTARecord` | Single Observation-Thought-Action cycle |
148
+| `CommitRecord` | Milestone commit snapshot |
149
+| `BranchMetadata` | Branch creation intent and status (YAML-serializable) |
150
+| `ContextResult` | Result of CONTEXT retrieval with `.Summary()` method |
151
+
152
+---
153
+
154
+## Directory Structure
155
+
156
+```
157
+your-project/
158
+ .GCC/
159
+ main.md # Global roadmap
160
+ branches/
161
+ main/
162
+ log.md # Continuous OTA trace
163
+ commit.md # Milestone-level summaries
164
+ metadata.yaml # Branch intent & status
165
+ feature-branch/
166
+ log.md
167
+ commit.md
168
+ metadata.yaml
169
+```
170
+
171
+All data is stored as **human-readable Markdown and YAML**.
172
+
173
+---
174
+
175
+## Running Tests
176
+
177
+```bash
178
+git clone https://github.com/swadhinbiswas/contexa.git
179
+cd contexa/GO
180
+go test -v ./cortexa/
181
+```
182
+
183
+20 tests cover all GCC commands: init, OTA logging, commit, branch, merge, context, switch, list, and model serialization.
184
+
185
+---
186
+
187
+## Requirements
188
+
189
+- **Go** >= 1.21
190
+- **gopkg.in/yaml.v3** -- YAML serialization for branch metadata
191
+
192
+---
193
+
194
+## License
195
+
196
+MIT License. See [LICENSE](LICENSE) for details.
197
+
198
+---
199
+
200
+## Citation
201
+
202
+```bibtex
203
+@article{wu2025gcc,
204
+ title={Git Context Controller: Manage the Context of LLM-based Agents like Git},
205
+ author={Wu, Junde and others},
206
+ journal={arXiv preprint arXiv:2508.00031},
207
+ year={2025}
208
+}
209
+```
210
+
211
+---
212
+
213
+## Links
214
+
215
+- [GitHub Repository](https://github.com/swadhinbiswas/contexa)
216
+- [pkg.go.dev](https://pkg.go.dev/github.com/swadhinbiswas/contexa)
217
+- [Original Paper](https://arxiv.org/abs/2508.00031)
218
+- [Author: Swadhin Biswas](https://github.com/swadhinbiswas)
0
219