Repo docs

Function Evolution Crawler: Usage Guide

The FunctionEvolutionCrawler is the sensory layer of the Evolution Engine. It is designed to create a "Genetic Baseline" of your code using Git tracking, SHA-256 hashing, and AST-based function extraction.

1. Setup & Environment

Ensure you have the following dependencies installed in your uv environment or via pip:

uv add litellm ipython


Ensure your project is a Git repository. The crawler uses Git to create snapshots before and after code changes.

2. Basic Initialization

The crawler defaults to looking for an evolve/ directory in your project root.

from function_crawler import FunctionEvolutionCrawler

# Initialize the crawler
# It will resolve the absolute path to your project root automatically
crawler = FunctionEvolutionCrawler()


3. The "Git Sandwich" Workflow

The recommended lifecycle for a mutation session is to "sandwich" your logic between the crawl() and finish_session() methods.

# Phase 1: Create baseline commit and build the in-memory registry
crawler.crawl()

# Phase 2: Perform your custom evolution logic here
# You can iterate through all functions found in the codebase
for mutation_obj in crawler.all_mutations():
    print(f"Analyzing: {mutation_obj.name}")
    # Example: Check if it's a class method
    if "." in mutation_obj.name:
        print("This is a class method.")

# Phase 3: Lock in the changes with a final commit
crawler.finish_session(note="Refactored utility functions")


4. Key Data Points

Every function identified by the crawler is stored as a FunctionMutation object with the following metadata:

Attribute

Description

name

Scoped name (e.g., MyClass.my_method or standalone_func).

content_hash

A unique SHA-256 signature of the function body.

docstring

The extracted """docstring""" if available.

selected_state

The current active version (usually a Git short-hash).

evolutions

A dictionary mapping versions to source code.

5. Persistence (Serialization)

To save the state of your codebase to a JSON file for analysis or for a separate LLM process:

# Saves to 'evolution_registry.json' by default (defined in CONFIG)
crawler.save_registry()


6. Configuration

You can modify the CONFIG dictionary at the top of function_crawler.py to change behavior without rewriting logic:

REGISTRY_FILE: Change the output name of the JSON data.

DEFAULT_EVOLVE_DIR: Change the target directory for the crawl.

IGNORE_PATTERNS: Add folders or file types to skip.