vichar 0.1.0__tar.gz

vichar-0.1.0/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to VICHAR are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+---
+
+## [0.1.0] — 2024-06-16
+
+### Added
+
+- **`vichar init`** — stamps `.vichar/project.json` with a UUID project identity,
+  writes `.vichar/CLAUDE.md`, `.vichar/cursor_rules`, `.vichar/SCHEMA.md`,
+  non-destructively injects `@.vichar/CLAUDE.md` into project `CLAUDE.md` and
+  inline block into `.cursor/rules` using `# --- VICHAR START/END ---` markers.
+  Interactive git prompt: `[L]ocal`, `[G]it`, `[S]kip`.
+
+- **`vichar capture`** — records a `decision`, `thread`, or `task` with `--type`,
+  `--body`, and `--author` flags. All entries stamped with `"schema": "1"`.
+  Atomic writes via `.tmp` + `os.replace()`. Cross-platform file locking
+  (`fcntl` on Unix, `msvcrt` on Windows).
+
+- **`vichar ratify <id>`** — marks an entry as human-confirmed (`proposed` → `ratified`).
+  Records `ratified_by` and `ratified_at`.
+
+- **`vichar close <id>`** — marks an entry as closed.
+
+- **`vichar log`** — rich ANSI table of open entries with status icons:
+  `V` (ratified), `?` (proposed), `o` (open), `X` (closed).
+  Body preview on second line. Warns about pre-schema entries.
+
+- **`vichar status`** — one-line project summary with entry counts by
+  type and status. `--json` flag for machine-readable output.
+
+- **`vichar migrate`** — upgrades pre-schema (`v0`) entries to schema v1.
+  `--dry-run` to preview changes. Backs up `entries.json` before writing.
+
+- **`vichar uninit`** — removes VICHAR injection blocks from `CLAUDE.md`
+  and `.cursor/rules`. Leaves `.vichar/` directory intact.
+
+- **`vichar-server`** — HTTP server on port 7474 (configurable via `--port`/`--host`).
+  Endpoints: `GET /` (HTML status page), `GET /status` (JSON), `GET /log` (JSON),
+  `POST /capture`, `POST /ratify`, `POST /close`.
+  Real-time coloured terminal output per event. Port conflict detection.
+  Graceful `Ctrl+C` shutdown.
+
+- **Zero external dependencies** — pure Python stdlib. Works on Python 3.8+.
+
+- **ANSI colours** — disabled automatically in CI (`NO_COLOR` env var),
+  non-TTY pipes, and enabled via `os.system("")` on Windows 10+.
+
+- **`pyproject.toml`** — PEP 621 packaging. Entry points for `vichar` and
+  `vichar-server` console scripts.
+
+- **`SCHEMA.md`** — documents all entry fields and schema versions.
+
+- **`.gitignore`** — standard Python ignores. `.vichar/` intentionally NOT
+  ignored in this repo (development entries are worth keeping).
+
+---
+
+## Pre-release (development)
+
+Initial design and prototyping captured in `.vichar/entries.json`
+(17 entries, including real decisions made during the build).

vichar-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Shivranjan Kolvankar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vichar-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include vichar.py
+include vichar_server.py

vichar-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: vichar
+Version: 0.1.0
+Summary: Versioned Intent and Context History for Agentic Reasoning — capture the why behind AI agent decisions
+Author-email: Shivranjan Kolvankar <shivranjankolvankar@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2024 Shivranjan Kolvankar
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/shivranjankolvankar/vichar
+Project-URL: Repository, https://github.com/shivranjankolvankar/vichar
+Keywords: ai,agent,reasoning,decision,claude,cursor,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# VICHAR — विचार
+
+**Versioned Intent and Context History for Agentic Reasoning**
+
+VICHAR captures *why* AI agents make decisions — not just what they do.
+Every decision, open question, and task is recorded so the next session
+(or a different agent) starts with full context instead of zero.
+
+---
+
+## Install
+
+```bash
+pip install vichar
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/shivranjankolvankar/vichar
+cd vichar
+pip install -e .
+```
+
+---
+
+## Quick start
+
+```bash
+# Initialise in your project
+cd my-project
+vichar init
+
+# Agents capture reasoning as they work
+vichar capture "Use FastAPI over Flask" \
+  --type decision \
+  --author claude-code \
+  --body "Flask lacks async support. FastAPI gives us OpenAPI docs for free."
+
+# At session start — read prior context
+vichar log
+
+# Confirm an entry (human ratification)
+vichar ratify abc12345
+
+# One-line project summary
+vichar status
+```
+
+---
+
+## Core concept: the trust gradient
+
+| Status | Meaning |
+|--------|---------|
+| `proposed` | Agent-written, unreviewed |
+| `ratified` | Human-confirmed |
+| `closed` | No longer relevant |
+
+Agents write freely. Humans decide what to trust.
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `vichar init` | Stamp project, write agent files, inject into CLAUDE.md + .cursor/rules |
+| `vichar capture "<text>"` | Capture a decision, thread, or task |
+| `vichar ratify <id>` | Mark an entry as human-confirmed |
+| `vichar close <id>` | Close an entry |
+| `vichar log` | Show open entries (rich table) |
+| `vichar status` | One-line project summary (add `--json` for machine output) |
+| `vichar migrate` | Upgrade pre-schema entries to schema v1 |
+| `vichar uninit` | Remove VICHAR injection from CLAUDE.md + .cursor/rules |
+| `vichar-server` | Start HTTP server on port 7474 (fallback for shell-less agents) |
+
+---
+
+## HTTP server (agent fallback)
+
+When an agent cannot run shell commands, it can POST over HTTP instead:
+
+```bash
+vichar-server [--port 7474] [--host 127.0.0.1]
+```
+
+```python
+import urllib.request, json
+
+def vichar(title, type="decision", body="", author="agent"):
+    data = json.dumps({"title": title, "type": type,
+                       "body": body, "author": author}).encode()
+    req = urllib.request.Request(
+        "http://localhost:7474/capture", data=data,
+        headers={"Content-Type": "application/json"}, method="POST")
+    try:
+        with urllib.request.urlopen(req, timeout=2) as r:
+            return json.loads(r.read())
+    except Exception:
+        return None  # never block on VICHAR
+```
+
+Server endpoints: `GET /`  `GET /status`  `GET /log`  `POST /capture`  `POST /ratify`  `POST /close`
+
+---
+
+## Agent integration
+
+`vichar init` writes instruction files and injects them automatically:
+
+- **Claude Code** (`CLAUDE.md`): injects `@.vichar/CLAUDE.md` import line  
+- **Cursor** (`.cursor/rules`): inlines the full instruction block  
+- Both injections are non-destructive (VICHAR START/END markers, idempotent)
+
+The agent files tell Claude / Cursor *when* to capture, *how* to capture, and the HTTP fallback snippet.
+
+---
+
+## What gets stored
+
+Each entry in `.vichar/entries.json` has:
+
+| Field | Description |
+|-------|-------------|
+| `id` | 8-char hex identifier |
+| `type` | `decision` / `thread` / `task` |
+| `status` | `proposed` / `ratified` / `closed` |
+| `title` | One-line summary |
+| `body` | Extended reasoning (markdown) |
+| `author` | `claude-code` / `cursor` / `human` / `agent` |
+| `schema` | `"1"` (schema version) |
+
+---
+
+## Zero dependencies
+
+VICHAR is pure Python stdlib — no `rich`, no `colorama`, no `click`.
+It works in any Python 3.8+ environment without `pip install` overhead.
+
+---
+
+## License
+
+MIT

vichar-0.1.0/README.md

@@ -0,0 +1,145 @@
+# VICHAR — विचार
+
+**Versioned Intent and Context History for Agentic Reasoning**
+
+VICHAR captures *why* AI agents make decisions — not just what they do.
+Every decision, open question, and task is recorded so the next session
+(or a different agent) starts with full context instead of zero.
+
+---
+
+## Install
+
+```bash
+pip install vichar
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/shivranjankolvankar/vichar
+cd vichar
+pip install -e .
+```
+
+---
+
+## Quick start
+
+```bash
+# Initialise in your project
+cd my-project
+vichar init
+
+# Agents capture reasoning as they work
+vichar capture "Use FastAPI over Flask" \
+  --type decision \
+  --author claude-code \
+  --body "Flask lacks async support. FastAPI gives us OpenAPI docs for free."
+
+# At session start — read prior context
+vichar log
+
+# Confirm an entry (human ratification)
+vichar ratify abc12345
+
+# One-line project summary
+vichar status
+```
+
+---
+
+## Core concept: the trust gradient
+
+| Status | Meaning |
+|--------|---------|
+| `proposed` | Agent-written, unreviewed |
+| `ratified` | Human-confirmed |
+| `closed` | No longer relevant |
+
+Agents write freely. Humans decide what to trust.
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `vichar init` | Stamp project, write agent files, inject into CLAUDE.md + .cursor/rules |
+| `vichar capture "<text>"` | Capture a decision, thread, or task |
+| `vichar ratify <id>` | Mark an entry as human-confirmed |
+| `vichar close <id>` | Close an entry |
+| `vichar log` | Show open entries (rich table) |
+| `vichar status` | One-line project summary (add `--json` for machine output) |
+| `vichar migrate` | Upgrade pre-schema entries to schema v1 |
+| `vichar uninit` | Remove VICHAR injection from CLAUDE.md + .cursor/rules |
+| `vichar-server` | Start HTTP server on port 7474 (fallback for shell-less agents) |
+
+---
+
+## HTTP server (agent fallback)
+
+When an agent cannot run shell commands, it can POST over HTTP instead:
+
+```bash
+vichar-server [--port 7474] [--host 127.0.0.1]
+```
+
+```python
+import urllib.request, json
+
+def vichar(title, type="decision", body="", author="agent"):
+    data = json.dumps({"title": title, "type": type,
+                       "body": body, "author": author}).encode()
+    req = urllib.request.Request(
+        "http://localhost:7474/capture", data=data,
+        headers={"Content-Type": "application/json"}, method="POST")
+    try:
+        with urllib.request.urlopen(req, timeout=2) as r:
+            return json.loads(r.read())
+    except Exception:
+        return None  # never block on VICHAR
+```
+
+Server endpoints: `GET /`  `GET /status`  `GET /log`  `POST /capture`  `POST /ratify`  `POST /close`
+
+---
+
+## Agent integration
+
+`vichar init` writes instruction files and injects them automatically:
+
+- **Claude Code** (`CLAUDE.md`): injects `@.vichar/CLAUDE.md` import line  
+- **Cursor** (`.cursor/rules`): inlines the full instruction block  
+- Both injections are non-destructive (VICHAR START/END markers, idempotent)
+
+The agent files tell Claude / Cursor *when* to capture, *how* to capture, and the HTTP fallback snippet.
+
+---
+
+## What gets stored
+
+Each entry in `.vichar/entries.json` has:
+
+| Field | Description |
+|-------|-------------|
+| `id` | 8-char hex identifier |
+| `type` | `decision` / `thread` / `task` |
+| `status` | `proposed` / `ratified` / `closed` |
+| `title` | One-line summary |
+| `body` | Extended reasoning (markdown) |
+| `author` | `claude-code` / `cursor` / `human` / `agent` |
+| `schema` | `"1"` (schema version) |
+
+---
+
+## Zero dependencies
+
+VICHAR is pure Python stdlib — no `rich`, no `colorama`, no `click`.
+It works in any Python 3.8+ environment without `pip install` overhead.
+
+---
+
+## License
+
+MIT

vichar-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vichar"
+version = "0.1.0"
+description = "Versioned Intent and Context History for Agentic Reasoning — capture the why behind AI agent decisions"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.8"
+authors = [{ name = "Shivranjan Kolvankar", email = "shivranjankolvankar@gmail.com" }]
+keywords = ["ai", "agent", "reasoning", "decision", "claude", "cursor", "llm"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Homepage = "https://github.com/shivranjankolvankar/vichar"
+Repository = "https://github.com/shivranjankolvankar/vichar"
+
+[project.scripts]
+vichar        = "vichar:main"
+vichar-server = "vichar_server:main"
+
+[tool.setuptools]
+py-modules = ["vichar", "vichar_server"]

vichar-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vichar-0.1.0/setup.py

@@ -0,0 +1,4 @@
+# Legacy shim — all metadata is in pyproject.toml (PEP 621).
+# This file exists only for editable installs on older pip versions.
+from setuptools import setup
+setup()