mi-crow 1.0.0.post1__py3-none-any.whl → 1.0.0.post2__py3-none-any.whl

{mi_crow-1.0.0.post1.dist-info → mi_crow-1.0.0.post2.dist-info}/METADATA

@@ -1,8 +1,11 @@
 Metadata-Version: 2.4
 Name: mi-crow
-Version: 1.0.0.post1
-Summary: Engineer Thesis: Explaining and modifying LLM responses using SAE and concepts.
-Author-email: Hubert Kowalski <your.email@example.com>, Adam Kaniasty <adam.kaniasty@gmail.com>
+Version: 1.0.0.post2
+Summary: Python library for mechanistic interpretability research on Large Language Models. Designed for researchers, provides unified interface for SAE training, activation hooks, and concept manipulation.
+Author: Hubert Kowalski
+Author-email: Adam Kaniasty <adam.kaniasty@gmail.com>
+Maintainer: Hubert Kowalski
+Maintainer-email: Adam Kaniasty <adam.kaniasty@gmail.com>
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: accelerate>=1.10.1
@@ -37,10 +40,153 @@ Requires-Dist: mkdocs-literate-nav>=0.6; extra == "docs"
 Requires-Dist: mkdocs-gen-files>=0.5; extra == "docs"
 Requires-Dist: mike>=2.1; extra == "docs"
 
-![CI](https://github.com/AdamKaniasty/Inzynierka/actions/workflows/tests.yml/badge.svg?branch=main)
+<div align="center">
+  <img src="docs/logo.svg" alt="Mi-Crow Logo" width="200">
+</div>
+
+# Mi-Crow: Mechanistic Interpretability for Large Language Models
+
+[![CI](https://github.com/AdamKaniasty/Inzynierka/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/AdamKaniasty/Inzynierka/actions)
+[![PyPI](https://img.shields.io/pypi/v/mi-crow)](https://pypi.org/project/mi-crow/)
 [![Docs](https://img.shields.io/badge/docs-gh--pages-blue)](https://adamkaniasty.github.io/Inzynierka/)
 
-## Running Tests
+**Mi-Crow** is a Python library for mechanistic interpretability research on Large Language Models (LLMs). Designed for researchers, it provides a unified interface for analyzing and controlling model behavior through Sparse Autoencoders (SAEs), activation hooks, and concept manipulation.
+
+## Features
+
+- **Unified Model Interface** - Work with any HuggingFace language model through a consistent API
+- **Sparse Autoencoder Training** - Train SAEs to extract interpretable features from model activations
+- **Hook System** - Intercept and manipulate model activations with minimal performance overhead
+- **Concept Discovery & Manipulation** - Discover and control model behavior through learned concepts
+- **Hierarchical Data Persistence** - Efficient storage and management of large-scale experiment data
+- **Research Focused** - Comprehensive testing (85%+ coverage), extensive documentation, and designed for interpretability research workflows
+
+## Installation
+
+### Install from PyPI
+
+```bash
+pip install mi-crow
+```
+
+### Install from Source
+
+```bash
+git clone https://github.com/AdamKaniasty/Mi-Crow.git
+cd Mi-Crow
+pip install -e .
+```
+
+### Requirements
+
+- **Python 3.12+** (required for modern type hints and features)
+- **PyTorch** - Tensor operations and neural networks
+- **Transformers** - Model loading and tokenization
+- **Accelerate** - Distributed and mixed-precision training
+- **Datasets** - Dataset loading and processing
+- **overcomplete** - SAE implementations
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from mi_crow.language_model import LanguageModel
+
+# Initialize a language model
+lm = LanguageModel(model_id="bielik")
+
+# Run inference
+outputs = lm.forwards(["Hello, world!"])
+
+# Access activations and outputs
+print(outputs.logits)
+```
+
+### Training an SAE
+
+```python
+from mi_crow.language_model import LanguageModel
+from mi_crow.mechanistic.sae import SaeTrainer
+from mi_crow.mechanistic.sae.modules import TopKSae
+
+# Load model and collect activations
+lm = LanguageModel(model_id="bielik")
+activations = lm.save_activations(
+    dataset=["Your text data here"],
+    layers=["transformer_h_0_attn_c_attn"]
+)
+
+# Train SAE
+trainer = SaeTrainer(
+    model=lm,
+    layer="transformer_h_0_attn_c_attn",
+    sae_class=TopKSae,
+    hyperparams={"epochs": 10, "batch_size": 256}
+)
+sae = trainer.train(activations)
+```
+
+### Concept Manipulation
+
+```python
+# Load concepts and manipulate model behavior
+concepts = lm.load_concepts(sae_id="your_sae_id")
+concepts.manipulate(neuron_idx=0, scale_factor=1.5)
+
+# Run inference with concept manipulation
+outputs = lm.forwards(
+    ["Your prompt"],
+    with_controllers=True,
+    concept_config=concepts
+)
+```
+
+## Documentation
+
+- **Full Documentation**: [adamkaniasty.github.io/Inzynierka](https://adamkaniasty.github.io/Inzynierka/)
+- **GitHub Repository**: [github.com/AdamKaniasty/Mi-Crow](https://github.com/AdamKaniasty/Mi-Crow/)
+- **Example Notebooks**: See `examples/` directory for Jupyter notebook tutorials
+
+## Architecture
+
+Mi-Crow follows a modular design with five core components:
+
+1. **`language_model/`** - Unified interface for language models
+   - Model initialization from HuggingFace Hub or local files
+   - Unified inference interface with mixed-precision support
+   - Architecture-agnostic layer abstraction
+
+2. **`hooks/`** - Flexible hook system for activation interception
+   - Detectors for observing activations
+   - Controllers for modifying model behavior
+   - Support for FORWARD and PRE_FORWARD hooks
+
+3. **`mechanistic/`** - SAE training and concept manipulation
+   - Sparse Autoencoder training (TopK, L1 variants)
+   - Concept dictionary management
+   - Concept-based model steering
+
+4. **`store/`** - Hierarchical data persistence
+   - Efficient tensor storage in safetensors format
+   - Batch iteration for large datasets
+   - Metadata management
+
+5. **`datasets/`** - Dataset loading and processing
+   - HuggingFace dataset integration
+   - Local file dataset support
+
+## Example Workflow
+
+See the example notebooks in the `examples/` directory:
+
+1. **`01_train_sae_model.ipynb`** - Train an SAE on model activations
+2. **`02_attach_sae_and_save_texts.ipynb`** - Collect top activating texts
+3. **`03_load_concepts.ipynb`** - Load and manipulate concepts
+
+## Development
+
+### Running Tests
 
 The project uses pytest for testing. Tests are organized into unit tests and end-to-end tests.
 
@@ -78,6 +224,45 @@ pytest tests/e2e -q
 
 The test suite is configured to require at least 85% code coverage. Coverage reports are generated in both terminal and XML formats.
 
+The project maintains **85%+ code coverage** requirement.
+
+### Code Quality
+
+- **Linting**: Ruff for code formatting and linting
+- **Pre-commit Hooks**: Automated quality checks
+- **Type Hints**: Extensive use of Python type annotations
+- **CI/CD**: GitHub Actions for automated testing and deployment
+
+## Citation
+
+If you use Mi-Crow in your research, please cite:
+
+```bibtex
+@thesis{kaniasty2025microw,
+  title={Mechanistic Interpretability for Large Language Models: A Production-Ready Framework},
+  author={Kaniasty, Adam and Kowalski, Hubert},
+  year={2025},
+  school={Warsaw University of Technology},
+  note={Engineering Thesis}
+}
+```
+
+## License
+
+See the main repository for license information: [Mi-Crow License](https://github.com/AdamKaniasty/Mi-Crow/)
+
+## Contact
+
+- **Maintainers**: Adam Kaniasty, Hubert Kowalski
+- **Email**: adam.kaniasty@gmail.com
+- **GitHub**: [@AdamKaniasty](https://github.com/AdamKaniasty)
+
+## Acknowledgments
+
+This work was developed in collaboration with the **Bielik** team and represents a contribution to the open-source mechanistic interpretability community.
+
+---
+
 ## Backend (FastAPI) quickstart
 
 Install server-only dependencies (kept out of the core library) with uv:

{mi_crow-1.0.0.post1.dist-info → mi_crow-1.0.0.post2.dist-info}/RECORD

@@ -48,7 +48,7 @@ mi_crow/store/__init__.py,sha256=DrYTpdgzrRzjHm9bigy-GiP0BGxzjmD3-lJCthtgxbE,123
 mi_crow/store/local_store.py,sha256=0Djh3zIVYWx_NASUv6VXfVLV3gRzTduFFgO7wswYcZA,17571
 mi_crow/store/store.py,sha256=ZxxIvhSPunUG7XsVGiDyqxk71Cmb0h-vSwLbZbDCRko,11299
 mi_crow/store/store_dataloader.py,sha256=UkZhHCOTg56ozomPtU9vHBhxIMOPcOiyfMqiAxgqtQs,4341
-mi_crow-1.0.0.post1.dist-info/METADATA,sha256=FzxoKA6dO57vsBg4exbG5CGfhIs1cuu9KW5sWVoEJgU,6617
-mi_crow-1.0.0.post1.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
-mi_crow-1.0.0.post1.dist-info/top_level.txt,sha256=DTuNo2VWgrH6jQKY19NciReSpLwGKKIRzJ3WbpspLlE,8
-mi_crow-1.0.0.post1.dist-info/RECORD,,
+mi_crow-1.0.0.post2.dist-info/METADATA,sha256=BUbZvRNArEuUWzk5fDV7z_CzzLgyrDNr-MAqiwE5ZiI,12475
+mi_crow-1.0.0.post2.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+mi_crow-1.0.0.post2.dist-info/top_level.txt,sha256=DTuNo2VWgrH6jQKY19NciReSpLwGKKIRzJ3WbpspLlE,8
+mi_crow-1.0.0.post2.dist-info/RECORD,,