swadhin / contexa public

rust: add package README for crates.io listing

Swadhin Biswas committed 7 months ago
8c0519f
1 parent b093fce
commit 8c0519f
1 file changed
+218 -0
Showing 1 changed file+218-0
RUST/README.md
▼RUST/README.md
+218-0
@@ -0,0 +1,218 @@
1
+# contexa
2
+
3
+[![Crates.io](https://img.shields.io/crates/v/contexa.svg)](https://crates.io/crates/contexa)
4
+[![docs.rs](https://docs.rs/contexa/badge.svg)](https://docs.rs/contexa)
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
+Rust 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
+```toml
19
+[dependencies]
20
+contexa = "0.1"
21
+```
22
+
23
+---
24
+
25
+## Quick Start
26
+
27
+```rust
28
+use contexa::GCCWorkspace;
29
+
30
+fn main() -> contexa::Result<()> {
31
+ let mut ws = GCCWorkspace::new("/path/to/project");
32
+ ws.init("Build a REST API service with user auth")?;
33
+
34
+ ws.log_ota(
35
+ "Project directory is empty",
36
+ "Need to scaffold the project structure first",
37
+ "create_files(['main.rs', 'Cargo.toml', 'models.rs'])",
38
+ )?;
39
+
40
+ ws.commit("Project scaffold and User model complete", None, None)?;
41
+
42
+ ws.branch("auth-jwt", "Explore JWT-based authentication")?;
43
+ ws.log_ota("Reading JWT docs", "JWT is stateless", "implement_jwt()")?;
44
+ ws.commit("JWT auth middleware implemented", None, None)?;
45
+
46
+ ws.merge("auth-jwt", None, "main")?;
47
+
48
+ let ctx = ws.context(None, 1)?; // K=1: paper default
49
+ println!("{}", ctx.summary());
50
+
51
+ Ok(())
52
+}
53
+```
54
+
55
+---
56
+
57
+## Core Concepts
58
+
59
+### OTA Logging (Observation-Thought-Action)
60
+
61
+```rust
62
+let rec = ws.log_ota(
63
+ "API returns 500 error on /users endpoint",
64
+ "The database connection might not be initialized",
65
+ "check_db_connection()",
66
+)?;
67
+println!("Step: {}", rec.step); // 1 (auto-incremented)
68
+println!("Timestamp: {}", rec.timestamp); // RFC3339
69
+```
70
+
71
+### COMMIT -- Save Milestones
72
+
73
+```rust
74
+let commit = ws.commit(
75
+ "Fixed database connection, /users now returns 200",
76
+ None, // previous summary auto-populated
77
+ Some("Database layer stable, move to auth"), // optional roadmap update
78
+)?;
79
+assert_eq!(commit.commit_id.len(), 8);
80
+assert_eq!(commit.branch_name, "main");
81
+```
82
+
83
+### BRANCH -- Explore Alternatives
84
+
85
+```rust
86
+ws.branch("redis-cache", "Try Redis caching instead of in-memory")?;
87
+ws.log_ota("Redis docs reviewed", "Need redis crate", "cargo add redis")?;
88
+ws.commit("Redis caching layer implemented", None, None)?;
89
+
90
+assert_eq!(ws.current_branch(), "redis-cache");
91
+println!("{:?}", ws.list_branches()); // ["main", "redis-cache"]
92
+```
93
+
94
+### MERGE -- Integrate Results
95
+
96
+```rust
97
+let merge_commit = ws.merge("redis-cache", None, "main")?;
98
+// Appends branch OTA trace to main's log
99
+// Creates a merge commit on main
100
+// Marks branch as "merged" in metadata
101
+assert_eq!(ws.current_branch(), "main");
102
+```
103
+
104
+### CONTEXT -- Retrieve History
105
+
106
+```rust
107
+let ctx = ws.context(None, 1)?; // K=1: paper default
108
+
109
+println!("{}", ctx.branch_name); // "main"
110
+println!("{}", ctx.main_roadmap); // Global project roadmap
111
+println!("{:?}", ctx.commits); // Last K CommitRecords
112
+println!("{:?}", ctx.ota_records); // All OTA records
113
+println!("{:?}", ctx.metadata); // BranchMetadata
114
+
115
+// Formatted markdown summary for LLM prompt injection
116
+println!("{}", ctx.summary());
117
+```
118
+
119
+---
120
+
121
+## API Overview
122
+
123
+### `GCCWorkspace`
124
+
125
+| Method | Signature | Description |
126
+|--------|-----------|-------------|
127
+| `new` | `(project_root: impl AsRef<Path>) -> Self` | Create workspace handle |
128
+| `init` | `(&mut self, roadmap: &str) -> Result<()>` | Create `.GCC/` structure |
129
+| `load` | `(&mut self) -> Result<()>` | Load existing workspace |
130
+| `log_ota` | `(&self, obs, thought, action) -> Result<OTARecord>` | Append OTA step |
131
+| `commit` | `(&self, contribution, prev?, roadmap?) -> Result<CommitRecord>` | Checkpoint milestone |
132
+| `branch` | `(&mut self, name, purpose) -> Result<()>` | Create and switch branch |
133
+| `merge` | `(&mut self, branch, summary?, target) -> Result<CommitRecord>` | Merge branch |
134
+| `context` | `(&self, branch?, k) -> Result<ContextResult>` | Retrieve context |
135
+| `switch_branch` | `(&mut self, name) -> Result<()>` | Switch active branch |
136
+| `list_branches` | `(&self) -> Vec<String>` | List all branches |
137
+| `current_branch` | `(&self) -> &str` | Get current branch |
138
+
139
+### Data Models
140
+
141
+| Struct | Description |
142
+|--------|-------------|
143
+| `OTARecord` | Single Observation-Thought-Action cycle |
144
+| `CommitRecord` | Milestone commit snapshot |
145
+| `BranchMetadata` | Branch creation intent and status (Serde-serializable) |
146
+| `ContextResult` | Result of CONTEXT retrieval with `.summary()` method |
147
+| `GCCError` | Error type covering IO, YAML, and workspace errors |
148
+
149
+---
150
+
151
+## Directory Structure
152
+
153
+```
154
+your-project/
155
+ .GCC/
156
+ main.md # Global roadmap
157
+ branches/
158
+ main/
159
+ log.md # Continuous OTA trace
160
+ commit.md # Milestone-level summaries
161
+ metadata.yaml # Branch intent & status
162
+ feature-branch/
163
+ log.md
164
+ commit.md
165
+ metadata.yaml
166
+```
167
+
168
+All data is stored as **human-readable Markdown and YAML**.
169
+
170
+---
171
+
172
+## Running Tests
173
+
174
+```bash
175
+git clone https://github.com/swadhinbiswas/contexa.git
176
+cd contexa/RUST
177
+cargo test
178
+```
179
+
180
+8 tests + 1 doc-test cover all GCC commands.
181
+
182
+---
183
+
184
+## Dependencies
185
+
186
+- **serde** + **serde_yaml** -- YAML serialization for branch metadata
187
+- **chrono** -- UTC timestamps (RFC3339)
188
+- **uuid** -- Commit ID generation (v4 UUIDs, first 8 chars)
189
+- **thiserror** -- Ergonomic error types
190
+
191
+---
192
+
193
+## License
194
+
195
+MIT License. See [LICENSE](LICENSE) for details.
196
+
197
+---
198
+
199
+## Citation
200
+
201
+```bibtex
202
+@article{wu2025gcc,
203
+ title={Git Context Controller: Manage the Context of LLM-based Agents like Git},
204
+ author={Wu, Junde and others},
205
+ journal={arXiv preprint arXiv:2508.00031},
206
+ year={2025}
207
+}
208
+```
209
+
210
+---
211
+
212
+## Links
213
+
214
+- [GitHub Repository](https://github.com/swadhinbiswas/contexa)
215
+- [crates.io](https://crates.io/crates/contexa)
216
+- [docs.rs](https://docs.rs/contexa)
217
+- [Original Paper](https://arxiv.org/abs/2508.00031)
218
+- [Author: Swadhin Biswas](https://github.com/swadhinbiswas)
0
219