cc-sentiment 0.1.1__tar.gz

cc_sentiment-0.1.1/.gitignore

@@ -0,0 +1,61 @@
+# macOS
+.DS_Store
+._*
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+build/
+dist/
+*.egg-info/
+*.egg
+.Python
+.venv/
+venv/
+.env
+.env.*
+
+# uv
+uv.lock
+
+# pytest / coverage
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+
+# mypy / pyright / ruff
+.mypy_cache/
+.ruff_cache/
+
+# Node / Bun
+node_modules/
+.svelte-kit/
+bun.lockb
+
+# MLX model artifacts
+*.safetensors
+*.gguf
+*.bin
+*.npz
+models/
+mlx_models/
+.mlx_cache/
+
+# Modal
+.modal/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Project
+.serena/
+.context/
+
+.claude/settings.local.json
+.vercel

cc_sentiment-0.1.1/AGENTS.md

@@ -0,0 +1,143 @@
+# client/ — macOS CLI
+
+macOS Apple Silicon CLI tool. Discovers Claude Code conversation transcripts, runs them through Gemma 4 via MLX for local sentiment analysis, signs results with GitHub SSH keys, and uploads to the server.
+
+## Tech Stack
+
+- **Runtime**: Python 3.12+, macOS Apple Silicon only
+- **ML inference**: MLX (`mlx-lm`) for local Gemma 4 inference on Apple Silicon GPU
+- **Model**: `mlx-community/gemma-4-e4b-it-4bit` (4-bit quantized, ~2.5GB) — also benchmark `unsloth/gemma-4-E4B-it-UD-MLX-4bit`
+- **CLI**: `click` or `typer`
+- **HTTP**: `httpx` for async uploads
+- **Signing**: `ssh-keygen -Y sign` via subprocess
+- **Packaging**: `uv tool install` from pyproject.toml with `[project.scripts]` entry point
+
+## Commands
+
+```bash
+uv sync                            # Install dependencies
+uv run cc-sentiment scan           # Discover and score new transcripts
+uv run cc-sentiment upload         # Upload pending scores to server
+uv run cc-sentiment scan --upload  # Scan and upload in one step
+uv run cc-sentiment setup          # Configure GitHub username, verify SSH keys
+uv run pytest client/              # Run tests
+```
+
+## Directory Structure (planned)
+
+```
+client/
+├── pyproject.toml
+├── cli.py              # CLI entry point (click/typer commands)
+├── transcripts.py      # Transcript discovery and parsing
+├── sentiment.py        # MLX inference, prompt construction, score extraction
+├── signing.py          # GitHub SSH key discovery and payload signing
+├── upload.py           # HTTP client for server API
+├── models.py           # Pydantic models for transcripts, scores, payloads
+└── tests/
+    ├── test_transcripts.py
+    ├── test_sentiment.py
+    ├── test_signing.py
+    └── fixtures/
+        └── sample_transcript.jsonl
+```
+
+## Transcript Discovery
+
+Claude Code stores conversations at `~/.claude/projects/<project-slug>/<uuid>.jsonl`. Each line is a JSON object representing a conversation turn.
+
+The client:
+1. Walks `~/.claude/projects/` recursively for `.jsonl` files
+2. Tracks already-processed files in `~/.cc-sentiment/state.json`
+3. Skips files unchanged since last scan (by mtime)
+4. Parses each JSONL file into a conversation
+
+### JSONL Structure
+
+Each line contains (at minimum):
+- `type`: message type (`human`, `assistant`, `tool_use`, `tool_result`, etc.)
+- `message`: the content object
+- Timestamps in conversation metadata
+
+Extract user messages (`type: "human"`) as the primary sentiment signal. Error tool results and assistant apologies are secondary signals.
+
+## MLX Inference
+
+### Model Loading
+
+```python
+from mlx_lm import load, generate
+
+model, tokenizer = load("mlx-community/gemma-4-e4b-it-4bit")
+```
+
+Model is downloaded once and cached in `~/.cache/huggingface/`.
+
+### Sentiment Prompt
+
+Score each conversation on a 1-5 Likert scale:
+- **1** — Deeply frustrated, angry, giving up
+- **2** — Annoyed, things aren't working
+- **3** — Neutral, transactional
+- **4** — Satisfied, things are working
+- **5** — Delighted, impressed, flow state
+
+The prompt must:
+- Present the conversation (or representative sample if too long)
+- Ask for a single integer score with brief justification
+- Use structured output (JSON) for reliable extraction
+- Be versioned — prompt changes shift the dataset, so the version is included in uploaded records
+
+### Inference Config
+
+- `max_tokens`: 100 (score + short justification)
+- `temperature`: 0.0 (deterministic scoring)
+- Each conversation gets its own inference call (context matters)
+
+## GitHub SSH Signing
+
+### Key Discovery
+
+Look for SSH keys in order:
+1. `~/.ssh/id_ed25519` (preferred)
+2. `~/.ssh/id_rsa`
+3. Keys listed in `~/.ssh/config`
+
+GitHub username from `git config github.user` or `~/.cc-sentiment/config.toml`.
+
+### Setup Flow
+
+`cc-sentiment setup`:
+1. Ask for GitHub username (or read from git config)
+2. Fetch `https://github.com/<username>.keys`
+3. Find matching local private key
+4. If no match: print instructions for adding an SSH key to GitHub
+5. Save config to `~/.cc-sentiment/config.toml`
+
+### Signing Protocol
+
+```bash
+echo '<canonical_json>' | ssh-keygen -Y sign -f ~/.ssh/id_ed25519 -n cc-sentiment
+```
+
+Namespace `cc-sentiment` prevents signature reuse across applications. Canonical JSON = sorted keys, compact encoding, no whitespace.
+
+## Upload Protocol
+
+1. Collect pending records (scored but not yet uploaded) from `~/.cc-sentiment/state.json`
+2. Serialize records to canonical JSON
+3. Sign with user's SSH key
+4. `POST` to server `/upload` with signed payload
+5. On success, mark records as uploaded in state
+6. On failure, retain for retry on next run
+
+## Style Specifics
+
+All rules from root `AGENTS.md` apply, plus:
+
+- **MLX isolated in `sentiment.py`.** No MLX imports leak into other modules. Keeps the CLI testable on non-Apple-Silicon (mock sentiment module).
+- **Subprocess calls use explicit argument lists.** Never `shell=True`. Always `subprocess.run(["ssh-keygen", "-Y", "sign", ...])`.
+- **Local state is a single JSON file.** `~/.cc-sentiment/state.json` for processed transcripts and pending uploads. No database for the client.
+- **CLI commands are thin.** Parse args, call library modules, format output. No business logic in CLI handlers.
+- **All network calls through `upload.py`.** Single module owns the HTTP client, base URL, retry logic.
+- **Fail loudly on wrong platform.** If MLX unavailable (not Apple Silicon), crash at import time with a clear message.

cc_sentiment-0.1.1/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

cc_sentiment-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yasyf Mohamedali
+
+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.

cc_sentiment-0.1.1/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: cc-sentiment
+Version: 0.1.1
+Summary: macOS CLI for Claude Code conversation sentiment analysis
+Project-URL: Homepage, https://sentiments.cc
+Project-URL: Repository, https://github.com/yasyf/cc-sentiment
+Project-URL: Issues, https://github.com/yasyf/cc-sentiment/issues
+Author-email: Yasyf Mohamedali <yasyfm@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: apple-silicon,claude-code,mlx,sentiment
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.13.11
+Requires-Dist: anyio>=4.4
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: mlx-lm>=0.20
+Requires-Dist: orjson>=3.10
+Requires-Dist: pydantic>=2.7
+Requires-Dist: python-gnupg>=0.5
+Requires-Dist: rich>=13.0
+Requires-Dist: tenacity>=8.0
+Requires-Dist: textual>=3.0
+Description-Content-Type: text/markdown
+
+# cc-sentiment
+
+A macOS CLI that scores your Claude Code conversations on-device and contributes the numbers to an open dashboard at [sentiments.cc](https://sentiments.cc).
+
+Your conversations stay on your Mac. Only anonymous numeric scores are uploaded.
+
+## Install & run
+
+The fast path — keeps the [omlx](https://github.com/jundot/omlx) grammar-constrained inference engine:
+
+```bash
+uvx --from https://sentiments.cc/run cc-sentiment
+```
+
+Or from PyPI (falls back to the pure `mlx-lm` engine):
+
+```bash
+uvx cc-sentiment
+```
+
+Requires macOS on Apple Silicon, Python 3.13+, and [uv](https://docs.astral.sh/uv/).
+
+The bare command walks you through setup (linking your GitHub account so uploads are attributable), scores your transcripts, and uploads the scores.
+
+## What gets uploaded
+
+Only numbers and timestamps. For each 5-minute bucket of a conversation:
+
+- Sentiment score (1–5, scored locally by Gemma 4)
+- Read:edit ratio, edits-without-prior-read %, write:edit ratio, tool calls per turn, subagent spawn rate
+- Turn count, thinking present/chars
+- Claude model and Claude Code version
+- Your GitHub handle (so uploads are attributable)
+
+Your conversation text, file contents, file paths, and tool inputs/outputs never leave your machine.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `cc-sentiment` | Run the whole flow — set up if needed, then scan and upload |
+| `cc-sentiment setup` | Link your GitHub account for attributable uploads |
+| `cc-sentiment scan --upload` | Score new transcripts and upload |
+| `cc-sentiment scan` | Score transcripts without uploading |
+| `cc-sentiment upload` | Upload previously scored results |
+| `cc-sentiment rescan` | Clear state and re-score everything |
+
+## Links
+
+- Dashboard: [sentiments.cc](https://sentiments.cc)
+- Source: [github.com/yasyf/cc-sentiment](https://github.com/yasyf/cc-sentiment)
+- Issues: [github.com/yasyf/cc-sentiment/issues](https://github.com/yasyf/cc-sentiment/issues)

cc_sentiment-0.1.1/README.md

@@ -0,0 +1,52 @@
+# cc-sentiment
+
+A macOS CLI that scores your Claude Code conversations on-device and contributes the numbers to an open dashboard at [sentiments.cc](https://sentiments.cc).
+
+Your conversations stay on your Mac. Only anonymous numeric scores are uploaded.
+
+## Install & run
+
+The fast path — keeps the [omlx](https://github.com/jundot/omlx) grammar-constrained inference engine:
+
+```bash
+uvx --from https://sentiments.cc/run cc-sentiment
+```
+
+Or from PyPI (falls back to the pure `mlx-lm` engine):
+
+```bash
+uvx cc-sentiment
+```
+
+Requires macOS on Apple Silicon, Python 3.13+, and [uv](https://docs.astral.sh/uv/).
+
+The bare command walks you through setup (linking your GitHub account so uploads are attributable), scores your transcripts, and uploads the scores.
+
+## What gets uploaded
+
+Only numbers and timestamps. For each 5-minute bucket of a conversation:
+
+- Sentiment score (1–5, scored locally by Gemma 4)
+- Read:edit ratio, edits-without-prior-read %, write:edit ratio, tool calls per turn, subagent spawn rate
+- Turn count, thinking present/chars
+- Claude model and Claude Code version
+- Your GitHub handle (so uploads are attributable)
+
+Your conversation text, file contents, file paths, and tool inputs/outputs never leave your machine.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `cc-sentiment` | Run the whole flow — set up if needed, then scan and upload |
+| `cc-sentiment setup` | Link your GitHub account for attributable uploads |
+| `cc-sentiment scan --upload` | Score new transcripts and upload |
+| `cc-sentiment scan` | Score transcripts without uploading |
+| `cc-sentiment upload` | Upload previously scored results |
+| `cc-sentiment rescan` | Clear state and re-score everything |
+
+## Links
+
+- Dashboard: [sentiments.cc](https://sentiments.cc)
+- Source: [github.com/yasyf/cc-sentiment](https://github.com/yasyf/cc-sentiment)
+- Issues: [github.com/yasyf/cc-sentiment/issues](https://github.com/yasyf/cc-sentiment/issues)