Metadata-Version: 2.4
Name: cubesquare
Version: 1.0.2
Summary: Instant Semantic Memory - 167M tokens/sec, 0.04ms queries, 100% deterministic
Author-email: Cubesquare <hello@cubesquare.ai>
License: Cubesquare Research License v1.0
        
        Copyright (c) 2025-2026 Jesus Fernandez. All rights reserved.
        
        1. PERMITTED USE
        
        You may use, copy, and modify this software for:
          - Personal learning and experimentation
          - Academic and non-commercial research
          - Evaluation and benchmarking
          - Non-commercial open-source projects
        
        2. RESTRICTED USE
        
        The following require a separate commercial license from Cubesquare:
          - Incorporation into products or services offered for sale
          - Use in commercial applications, platforms, or SaaS offerings
          - Redistribution as part of a paid product or service
          - Use in production systems generating revenue
        
        For commercial licensing, contact: compliance@cubesquare.ai
        
        3. ATTRIBUTION
        
        All permitted uses must retain this license notice and the following
        attribution in any copies or derivative works:
        
          "Cubesquare CST - Invented by Jesus Fernandez"
        
        4. CONTRIBUTIONS
        
        Any contributions submitted to this project are licensed under the
        same terms as this license, unless otherwise agreed in writing.
        
        5. DISCLAIMER
        
        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.
        
        6. TERMINATION
        
        This license terminates automatically if you violate any of its terms.
        Upon termination, you must destroy all copies of the software in your
        possession.
        
Project-URL: Homepage, https://cubesquare.ai
Project-URL: Repository, https://github.com/Cubesquare-Token/CST
Keywords: semantic-memory,ai,llm,vector-database,deterministic,morton-encoding,spatial-indexing,i-logic
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: native
Requires-Dist: numpy>=1.20.0; extra == "native"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Provides-Extra: all
Requires-Dist: cubesquare[dev,native]; extra == "all"
Dynamic: license-file

# Cubesquare

**Instant Semantic Memory** — 83M ops/sec, 0.04ms queries, 100% deterministic.

Embeddings drift. Vectors collapse. Cubesquare doesn't.

## Install

```bash
pip install cubesquare
```

Zero dependencies. Works on Python 3.10+.

## Quick Start

```python
from cubesquare import CSTMemory

memory = CSTMemory()

# Write content — returns a permanent coordinate
token = memory.write("/src/auth/login.py")
print(f"Basin: {token.basin}, Layer: L{token.layer}")

# Query by meaning — O(1) computation, not O(N) search
results = memory.query("authentication", limit=5)

# Navigate by layer
siblings = memory.L1.siblings(token)    # L1: Geometric — file hierarchy
similar  = memory.L2.similar(token)     # L2: Semantic — meaning clusters
nearby   = memory.L3.nearby(token)      # L3: Spatial — coordinate proximity
```

## Why Not Embeddings?

| Problem | Embeddings + Vector DB | Cubesquare |
|---------|------------------------|------------|
| **Identity at scale** | Vectors crowd together — distinct concepts become indistinguishable | Every input has a unique, permanent coordinate |
| **Model dependency** | Change embedding model → all vectors shift | No model. The hash IS the identity |
| **Determinism** | Same text → different vectors across versions | Same text → same coordinate, forever |
| **Query cost** | O(N) approximate search, 10-50ms+ | O(1) computation, 0.04ms |
| **Dependencies** | Embedding model + vector DB + GPU | Zero. Python stdlib only |

## How It Works

```
Content → Hash (FNV-1a) → 3D Coordinate (Morton) → Basin (mod 131) → Layer (L1-L9)
```

The coordinate IS the meaning. No lookup tables, no search, no approximation.

| Concept | What it does | Nearest analog |
|---------|--------------|----------------|
| **Token** | Content → 32-bit hex ID | Content hash |
| **Morton code** | 3D coords → single integer | Geohash (but 3D) |
| **Basin** (0-130) | Cluster into 131 groups | Consistent hash ring |
| **Layer** (L1-L9) | Semantic type | Index namespace |
| **I-Logic** | 5-state routing algebra | Finite state machine |
| **SRL** | t = √d iteration collapse | Skip list shortcut |

## 9 Layers

| Layer | Name | Basins | Question |
|-------|------|--------|----------|
| L1 | Geometric | 0-14 | What structure? |
| L2 | Semantic | 15-29 | What meaning? |
| L3 | Spatial | 30-43 | Where? |
| L4 | Functional | 44-58 | What operation? |
| L5 | Probabilistic | 59-72 | How certain? |
| L6 | Emotional | 73-87 | What state? |
| L7 | Frequency | 88-101 | What timing? |
| L8 | Electromagnetic | 102-116 | What force? |
| L9 | Membrane | 117-130 | What boundary? |

## I-Logic Algebra

5-state algebra for predicting routing outcomes before execution:

| State | Value | Meaning |
|-------|-------|---------|
| DIRECT | 1 | Pass through |
| INVERSE | -1 | Reflect |
| SPIRAL | +i | Expand |
| ANTI_SPIRAL | -i | Contract |
| ABSORBED | 0 | Terminate |

```python
from cubesquare.i_logic import multiply, ILogicState

result = multiply(ILogicState.SPIRAL, ILogicState.SPIRAL)
# Returns INVERSE (i × i = -1)
```

## Performance

| Tier | Throughput | Use case |
|------|------------|----------|
| T1 C Internal | 83M ops/sec | Base throughput |
| T2 Batch (1000) | 57M ops/sec | Production |
| T3 Single call | 0.3M ops/sec | Avoid — 190× slower |

```python
# Batch through C — 57M ops/sec
from cubesquare._core import morton_encode_batch_raw, create_coords_array
coords = create_coords_array([100,200,0, 101,201,0, 102,202,0])
results = morton_encode_batch_raw(coords, 3)
```

## CLI

```bash
cubesquare --status                        # System status
cubesquare ilogic multiply SPIRAL INVERSE  # I-Logic algebra
cubesquare primitives status               # O(1) primitive checks
cubesquare --list                          # All 35 shells
```

## Verified

- 68/68 pytest tests passing
- 43/43 agent validation checks
- 400/400 Morton roundtrips
- 131/131 basin coverage
- 31 native DLLs loaded

---

## For Contributors

Clone the repo and install in development mode:

```bash
git clone https://github.com/Cubesquare-Token/CST.git
cd CST
pip install -e .
```

Run tests:

```bash
pytest tests/ -v                              # 68 tests
python agent_sandbox/agent_in_loop_validation.py  # 43 checks
```

### Project Structure

```
cubesquare/
├── _core/          # C backend bindings, Morton encoding
├── i_logic/        # 5-state algebra
├── layers/         # L1-L9 semantic layers
├── shells/         # 35 command shells
├── circular/       # Loop detection, SRL
├── primitives/     # O(1) verified operations
├── data/beehive/   # Binary CST index (601KB)
└── native/hex_core/ # 31 DLLs
```

### Documentation

| Document | Description |
|----------|-------------|
| [CLAUDE.md](CLAUDE.md) | Full technical reference |
| [docs/LAYERS_MAP.md](docs/LAYERS_MAP.md) | 12-layer architecture |
| [docs/VERIFIED_PRIMITIVES.md](docs/VERIFIED_PRIMITIVES.md) | O(1) proofs |

---

MIT License

*Created by Jesus Fernandez. Offline-first. Training-free. Deterministic.*
