# fractal-search

Multi-scale document search with φ-weighted decay. Search meaning, not just text.

## What it does

Documents are indexed at three scales — document, section, paragraph — like a fractal. Search results are weighted by the golden ratio (φ = 1.618) so direct matches score highest and related matches decay naturally.

```
Document level    → weight: 1.0
Section level     → weight: 1/φ ≈ 0.618
Paragraph level   → weight: 1/φ² ≈ 0.382
Related terms     → weight: 1/φ³ ≈ 0.236
```

## Install

```bash
pip install fractal-search
```

## CLI Usage

```bash
# Search file contents
fsearch "your query" ~/Documents/

# Search filenames only
fsearch "bazinga deploy" ~/Projects/ --names

# Clean output (just paths, pipeable)
fsearch "darmiyan" ~/Research/ --paths-only

# JSON output
fsearch "trust dimension" . --json

# Verbose with pattern explanations
fsearch "SSRI calcium" ~/papers/ -v --max 20
```

## Python API

```python
from fractal_search import FractalSearchEngine

engine = FractalSearchEngine()

# Add individual documents
engine.add("doc1", "My Paper", "Content about fractals...")
engine.add("doc2", "My Notes", "Something about cooking...")

# Or index a directory
engine.add_directory("~/Documents/", extensions=('.md', '.txt', '.py'))

# Search
results = engine.search("fractal patterns")
for r in results:
    print(f"{r.score:.1f}  {r.title}  {r.doc_id}")
    print(f"  terms: {r.matching_terms}")
    print(f"  snippet: {r.snippet[:100]}")
```

## How it works

1. **Multi-scale fingerprinting** — Each document is tokenized at three levels (whole → sections → paragraphs), creating a self-similar index structure
2. **φ-weighted decay** — Results at deeper index levels are weighted by 1/φ per level, using the golden ratio as the optimal relevance decay
3. **Co-occurrence sub-indexing** — Frequently co-occurring terms create sub-indices (fractal branching), so searching "SSRI" also surfaces "sertraline" and "emotional blunting"
4. **Adaptive depth** — Search depth auto-adjusts based on query complexity using Fibonacci sequence modulation

## Why φ?

The golden ratio is the fixed point of self-reference: φ - 1 = 1/φ. It's the optimal boundary between local relevance (this paragraph) and global relevance (the whole document). This isn't arbitrary — it's the same ratio that appears in natural information structures from DNA to galaxies.

## Author

Abhishek Srivastava — [github.com/0x-auth](https://github.com/0x-auth)

## License

MIT
