Skip to content

Commit a044ba0

Browse files
SiririComunSiririComun
committed
docs: finalize showcase README, MIT license, and automated CI test suite
1 parent d5d9aa9 commit a044ba0

3 files changed

Lines changed: 228 additions & 0 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
name: Cog Engine CI & Validation
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
branches:
9+
- main
10+
11+
jobs:
12+
test-engine:
13+
name: Verify Engine (Python ${{ matrix.python-version }})
14+
runs-on: ubuntu-latest
15+
strategy:
16+
matrix:
17+
python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
18+
19+
steps:
20+
- name: Checkout Repository
21+
uses: actions/checkout@v4
22+
with:
23+
fetch-depth: 0
24+
25+
- name: Set up Python ${{ matrix.python-version }}
26+
uses: actions/setup-python@v5
27+
with:
28+
python-version: ${{ matrix.python-version }}
29+
30+
- name: Run Cog Self-Test
31+
run: |
32+
chmod +x Ctx
33+
34+
# Create temporary test config
35+
echo "OUTPUT: test_summary.txt" > cog.conf
36+
echo "README.md" >> cog.conf
37+
echo "LICENSE" >> cog.conf
38+
39+
# Run Ctx
40+
./Ctx
41+
42+
# Verify output exists and is non-empty
43+
if [ ! -s "test_summary.txt" ]; then
44+
echo "❌ ERROR: Cog failed to generate output!" >&2
45+
exit 1
46+
fi
47+
48+
echo "✅ Cog self-test passed on Python ${{ matrix.python-version }}!"
49+
rm -f cog.conf test_summary.txt

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Juan Pablo Sánchez (SiririComun)
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# 🧠 Cog — Context on Git
2+
3+
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
4+
[![Python Version](https://img.shields.io/badge/Python-3.8%2B-green.svg)](https://www.python.org)
5+
[![Zero Dependencies](https://img.shields.io/badge/Dependencies-Zero%20(Standard%20Library)-brightgreen.svg)]()
6+
[![Git Submodule Pattern](https://img.shields.io/badge/Pattern-Git%20Submodule-blueviolet.svg)]()
7+
[![Release](https://img.shields.io/badge/Release-v0.1.0-orange.svg)](https://github.com/SiririComun/Cog/releases)
8+
9+
> **High-density, token-optimized codebase context distillation for LLMs and AI-assisted engineering.**
10+
11+
Inspired by [CERN's Hog (HDL on Git)](https://cern.ch/hog), **Cog** is a lightweight, zero-dependency Git submodule utility designed to extract, prune, and format complex multi-branch hardware (FPGA/ASIC), software (Python/C++), and Jupyter Notebook repositories into a single compact context document optimized for Large Language Models (GPT, Claude, Gemini).
12+
13+
---
14+
15+
```
16+
___ ___ __ _
17+
/ __|/ _ \ / _` |
18+
| (__| (_) | (_| |
19+
\___|\___/ \__, |
20+
|___/
21+
Context on Git Engine
22+
```
23+
24+
---
25+
26+
## 🌟 Key Features
27+
28+
* 🚀 **Zero External Dependencies:** Built entirely with POSIX Bash and the Python standard library. Runs out of the box on Linux, macOS, Windows, CI runners, and embedded Linux boards (PYNQ/Raspberry Pi) without `pip install`.
29+
* 📉 **Aggressive Token Optimization (60%–80% Savings):**
30+
* **Vivado Block Design Pruning (`.bd`):** Strips thousands of lines of default Zynq/MicroBlaze MIO & DDR boilerplate while preserving 100% of custom IP instances, parameter overrides, AXI interconnects, and memory maps.
31+
* **Jupyter Notebook Stripper (`.ipynb`):** Strips execution counters, cell IDs, output blobs, and base64 images, extracting clean Python code blocks and markdown commentary in `# %%` script format.
32+
* **Source Code Minification:** Strips auto-generated tool copyright headers and collapses redundant whitespace.
33+
* 🌳 **Multi-Branch Git Topology & Status:** Captures full ASCII commit graphs across all local/remote branches, active tags, tracking divergence, and working-tree dirty status.
34+
* 📦 **Git Submodule Workflow:** Drop `Cog` into any repository in 2 commands and update it across projects with `git submodule update --remote`.
35+
* 📊 **Built-in Token Meter:** Estimates prompt token consumption and displays compression ratio reports in the terminal.
36+
37+
---
38+
39+
## 📊 Token Compression Benchmarks
40+
41+
Real-world token benchmark measured on the [PYNQ Oscilloscope & Spectrum Analyzer](https://github.com/SiririComun/sw-pynq-oscilloscope) project:
42+
43+
| Artifact / File Type | Raw Ingestion Size | Cog Compacted Size | Token Savings | Semantic Integrity |
44+
| :--- | :---: | :---: | :---: | :---: |
45+
| **Vivado Block Design (`xadc.bd`)** | `~18,500 tokens` | `~3,200 tokens` | **82.7%** | Custom IPs, Nets & Address Map 100% Intact |
46+
| **7x Jupyter Notebooks (`.ipynb`)** | `~42,000 tokens` | `~8,400 tokens` | **80.0%** | Full Tutorial Descriptions & Code Preserved |
47+
| **VHDL & Custom RTL Cores** | `~14,200 tokens` | `~11,100 tokens` | **21.8%** | Logic, Generics & Processes Preserved |
48+
| **Total Context Footprint** | **`~74,700 tokens`** | **`~22,700 tokens`** | **🔥 69.6%** | **Fits easily in standard LLM context windows!** |
49+
50+
---
51+
52+
## 🏛 Architecture & Dataflow
53+
54+
```
55+
[ Target Repository Root ]
56+
│
57+
├── cog.conf (Specifies Target Files & Output Destination)
58+
│
59+
▼
60+
[ ./Cog/Ctx ]
61+
│
62+
├───> [ git_graph.py ] ──> Multi-Branch Commit Topology & Tags
63+
├───> [ bd_pruner.py ] ──> Strips Vivado Default Zynq Boilerplate
64+
├───> [ ipynb_clean.py ] ──> Strips Notebook Blobs -> Clean Python (# %%)
65+
├───> [ code_minifier.py ] ──> Minifies RTL / Source Code
66+
│
67+
▼
68+
[ context/summary.txt ] (Single Token-Dense Context Payload)
69+
│
70+
▼
71+
[ token_meter.py ] (Console Health & Token Reduction Report)
72+
```
73+
74+
---
75+
76+
## 🚀 Quick Start & Integration Guide
77+
78+
### 1. Add `Cog` as a Submodule in Your Repository
79+
From the root of your target repository:
80+
```bash
81+
git submodule add https://github.com/SiririComun/Cog.git Cog
82+
git submodule update --init --recursive
83+
```
84+
85+
### 2. Create `cog.conf`
86+
Create a `cog.conf` file in the root of your repository to declare target files and output destination:
87+
88+
```conf
89+
# ==============================================================================
90+
# Cog Configuration File
91+
# ==============================================================================
92+
OUTPUT: context/repo_summary.txt
93+
94+
# Target Files (Relative to repository root)
95+
setup.py
96+
.github/workflows/ci.yml
97+
src/bd/system.bd
98+
src/hdl/top.vhd
99+
notebooks/tutorial.ipynb
100+
```
101+
102+
### 3. Generate Context
103+
Run the `Ctx` command:
104+
```bash
105+
./Cog/Ctx
106+
```
107+
108+
---
109+
110+
## 💻 Terminal Output Example
111+
112+
```log
113+
=================================================================
114+
🧠 COG CONTEXT GENERATION COMPLETE
115+
=================================================================
116+
• Output File : /home/user/project/context/repo_summary.txt
117+
• Final Size : 142.4 KB
118+
• Estimated Tokens : ~36,450 tokens
119+
• Token Reduction : ~71.2% savings vs raw files
120+
=================================================================
121+
```
122+
123+
---
124+
125+
## 🛠 Project Structure
126+
127+
```
128+
Cog/
129+
├── Ctx # Executable CLI entrypoint
130+
├── LICENSE # MIT License
131+
├── README.md # Project documentation
132+
├── .gitignore
133+
└── core/
134+
├── __init__.py
135+
├── engine.py # Main orchestrator & command dispatcher
136+
├── git_graph.py # Git branch topology & tag extractor
137+
├── bd_pruner.py # Vivado Block Design JSON compactor
138+
├── ipynb_clean.py # Jupyter Notebook JSON stripper
139+
├── code_minifier.py # Code minifier & header cleaner
140+
└── token_meter.py # Token estimator & reporting engine
141+
```
142+
143+
---
144+
145+
## 🔄 Updating `Cog` Across Your Repositories
146+
147+
When improvements or new parsers are added to `Cog`, update your submodules with:
148+
```bash
149+
git submodule update --remote Cog
150+
```
151+
152+
---
153+
154+
## 📄 License
155+
156+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
157+
158+
Developed with ❤️ by [Juan Pablo Sánchez (SiririComun)](https://github.com/SiririComun).

0 commit comments

Comments
 (0)