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

pip install fractal-search

CLI Usage

# 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

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

License

MIT