Metadata-Version: 2.4
Name: cos-comparison
Version: 0.1.4
Summary: An AGI-spurting work (experimental stage now) based on local similarity comparison for feature extraction – biologically inspired, zero‑training edge / pattern detection.
Author: Li Jinxin
License-Expression: MIT
Project-URL: Homepage, https://pypi.org/project/cos-comparison/
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Provides-Extra: numpy
Requires-Dist: numpy>=1.20; extra == "numpy"
Dynamic: license-file

# Cos Comparison

[![PyPI version](https://badge.fury.io/py/cos-comparison.svg)](https://pypi.org/project/cos-comparison/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Local similarity comparison for feature extraction – biologically inspired, zero‑training edge / pattern detection.**

## Core Idea

Information is produced by **local comparison** in raw data.  
This module implements the **centre‑surround antagonism** mechanism from neuroscience, extracting edges, textures, and keypoints using only sliding window similarity.

The main formula (cosine‑modulated similarity):

$$ \text{cosmod} = \frac{2\,(A\cdot B)}{\|A\|^2 + \|B\|^2} $$

- **Spurt for real AGI**
- **No training, no labels, no backpropagation**
- Works on **1D, 2D, 3D, 4D** data (audio, images, video, volumes)
- Supports **passive** (reflex) and **active** (template matching) modes
- Pure Python core + optional **NumPy / C acceleration**

## Core Principles

1. **Information is generated by local comparison** – edges, textures, patterns arise from comparing neighbouring regions.
2. **Centre‑surround antagonism** – two sliding windows compared with a fixed displacement vector `d`, mimicking retinal ganglion cells.
3. **Three complementary similarity measures** – `cos` (angular), `mod` (magnitude), `cosmod` (recommended combination).
4. **Dual operational modes** – **passive** (detects boundaries without templates) and **active** (template matching with user‑supplied kernel).
5. **Multi‑scale and multi‑directionality** – vary window size for scale, change `d` for orientation selectivity (vertical, horizontal, diagonal).
6. **Dimension‑agnostic** – same algorithm works on 1D, 2D, 3D, 4D and beyond.
7. **Zero training, zero labels** – deterministic computation, ready to use.
8. **Full determinism and interpretability** – every output has a clear geometric meaning.
9. **Modular, pluggable architecture** – pure Python reference, NumPy vectorised, C high‑performance backends with automatic fallback.

See [core_base.txt](https://pypi.org/project/cos-comparison/) for the complete design philosophy.

## ⚠️ Warning

**This is an experimental version!**  
- Do **not** use it in a productive environment.  
- All interfaces may change during the experimental stage, although I will try to keep it as stable as possible.  
- Do **not** share this software with others without including this warning.

## Roadmap & How to Contribute

This is still an early‑stage project. You can:

- **Fix bugs** and report issues.
- **Compare** with other algorithms (deep learning, classical filters) on standard benchmarks.
- **Test on diverse datasets** – time series, medical images, audio, video.
- **Develop the core ideas** – propose new similarity metrics, add GPU backends, or integrate into larger pipelines.

If you encounter import errors after installation, try modifying the package's `__init__.py`:

```python
from cos_comparison import *
```

## Installation

```bash
pip install cos-comparison
```

## Quick Start

```python
import cos_comparison as cc

# 1D passive: find similar segments
data = [1.0, 2.0, 3.0, 4.0, 5.0]
result = cc.cos_comparison_passive_1d(data, window_size=(2,), step=(1,), d=(1,))
print(result)

# 2D passive: edge detection
image = [[1,1,0,0], [1,1,0,0], [0,0,1,1], [0,0,1,1]]
edges = cc.cos_comparison_passive_2d(image, window_size=(2,2), step=(1,1), d=(1,0))
print(edges)

# Active mode – template matching
kernel = [1.0, 0.0]
result_active = cc.cos_comparison_active_1d(data, kernel=kernel, step=(1,))
print(result_active)

# Whole‑tensor cosine
a, b = [1,2,3], [2,3,4]
sim = cc.cos_1d(a, b)
print(sim)
```

## Optional Backends

The package automatically selects the fastest available backend:

| Priority | Backend      | Requirement                                      |
|:---------|:-------------|:-------------------------------------------------|
| 1        | C            | Compile `cos_comparison_c/include/core.c`        |
| 2        | NumPy        | `pip install numpy`                              |
| 3        | Pure Python  | Works out of the box                             |

Force a specific backend via environment variable:
```bash
export COS_BACKEND=cos_comparison,cos_comparison_numpy
```

## API Overview

### Passive mode (self‑similarity)
`cos_comparison_passive_1d` / `_2d` / `_3d` / `_4d` + generic N‑dim

### Active mode (template matching)
`cos_comparison_active_1d` / `_2d` / `_3d` / `_4d` + generic N‑dim

### Whole‑tensor cosine
`cos_1d` / `_2d` / `_3d` / `_4d`

### Statistics
`mean_local_*` / `local_variance_*` – sliding window mean and variance

### Command line
```bash
python -m cos_comparison passive --data input.json --window 3 3 --output out.json
```

## License

MIT © 2025 Li Jinxin. See [LICENSE](https://pypi.org/project/cos-comparison/) for details.
