BranchPy
Log in

Docs-Builder

title: “BranchPy API Reference” version: 1.1.1 date: 2026-01-23

BranchPy API Reference v1.1.1

Complete API documentation for BranchPy’s Python and TypeScript interfaces.

Version: 1.1.1
Last Updated: January 23, 2026

Documentation Structure

  • API Contracts - Complete endpoint documentation, request/response formats, and examples
  • Error Handling - API error codes, exception hierarchy, and error handling patterns

Core APIs

branchpy.ai

AI integration with multi-provider support (OpenAI, Anthropic, Ollama, Venice.ai).

Key Features:

  • Code review and refactoring suggestions
  • Warning explanations
  • Documentation generation
  • Privacy-preserving governance
  • Local AI support

Main Classes:

  • AIProvider - Provider protocol
  • ProviderManager - Provider management
  • ChatRequest/ChatResponse - Request/response models
  • AICodeReviewer - Code review engine
  • AIWarningExplainer - Warning explanation engine
  • AIRefactorSuggester - Refactoring suggestions

branchpy.license

Authentication and feature entitlements system.

Key Features:

  • JWT-based authentication
  • Plan-based feature gating
  • Device management
  • Offline mode (30-day grace period)
  • Engine detection (auto-detect Ren’Py)

Main Functions:

  • login() / logout() - Authentication
  • has_feature() / require_feature() - Feature gating
  • get_plan() - Get current plan
  • detect_engine() - Auto-detect game engine

branchpy.semantics

Semantic analysis including AST parsing and control flow.

Key Features:

  • Python AST parsing
  • Cross-file label tracking
  • Expression propagation
  • Dynamic path extraction
  • CFG visualization

Main Classes:

  • PythonASTParser - Parse Python blocks
  • CrossFileTracker - Track labels across files
  • ExpressionPropagationEngine - Data flow analysis
  • DynamicPathExtractor - Media reference extraction
  • MediaScannerCache - High-performance file scanning

branchpy.quickfix

Code transformation and refactoring operations.

Key Features:

  • Variable inlining/extraction
  • f-string conversion
  • Line splitting
  • Type hint inference
  • Call graph visualization

Main Classes:

  • InlineVariableOperation - Inline variable usage
  • ExtractVariableOperation - Extract expressions
  • ConvertToFStringOperation - Modernize string formatting
  • SplitLongLineOperation - Break long lines
  • AddTypeHintsOperation - Add type annotations

branchpy.performance

Performance optimization utilities.

Key Features:

  • File hash caching
  • AST caching with LRU
  • Memoized analysis
  • Parallel processing
  • Performance timers

Main Classes:

  • FileHashCache - File change detection
  • ASTCache - AST tree caching
  • MemoizedAnalysis - Result caching
  • PerformanceTimer - Execution timing

Supporting APIs

branchpy.core

Core functionality including diffing, filesystem, and project models.

Modules:

  • diffing - Diff algorithms
  • fs - Filesystem utilities
  • jsonio - JSON I/O
  • patches - Patch management
  • project_model - Project orchestration
  • engine_interface - Multi-engine architecture (AXIS3)

branchpy.contract

Public contracts, constants, and versioning.

Features:

  • Version information
  • Exit codes
  • Error kinds
  • API boilerplate

branchpy.errors

Exception hierarchy and error handling.

Main Exceptions:

  • BranchPyError - Base exception
  • ParseError - Parsing failures
  • ValidationError - Validation failures
  • ConfigError - Configuration issues

branchpy.config-store

Configuration management system.

Features:

  • Project-level config
  • Global config
  • Config validation
  • Config migration

branchpy.scan-context

Scan context management for analysis.

Features:

  • File scanning
  • Ignore patterns
  • Include patterns
  • Metadata extraction

branchpy.telemetry

Telemetry and analytics system.

Features:

  • Event tracking
  • Error reporting
  • Usage statistics
  • Privacy controls

branchpy.logging

Logging infrastructure.

Features:

  • Structured logging
  • Log levels
  • Log formatting
  • Log rotation

branchpy.utils

Utility functions and helpers.

Features:

  • Path utilities
  • String utilities
  • Collection utilities
  • Validation helpers

branchpy.update-manager

Update checking and management.

Features:

  • Version checking
  • Update notifications
  • Release notes
  • Update installation

API Categories

Analysis & Parsing

AI & Intelligence

Authentication & Licensing

Performance & Optimization

Infrastructure

Usage Patterns

Basic Analysis

from branchpy.semantics import PythonASTParser, CrossFileTracker

# Parse files
parser = PythonASTParser()
tracker = CrossFileTracker()

for file in script_files:
    ast = parser.parse_file(file)
    tracker.add_file(file, ast)

# Analyze
tracker.resolve_all_references()
warnings = tracker.find_unreachable_labels()

AI-Powered Features

from branchpy.ai import ProviderManager
from branchpy.ai.ast_integration import AICodeReviewer
from branchpy.license import require_feature

# Check license
require_feature("ai_review")

# Initialize
manager = ProviderManager()
reviewer = AICodeReviewer(manager)

# Review code
result = reviewer.review_code(source_code, file_path)

Feature-Gated Commands

from branchpy.license import require_feature, has_feature

# Enforce feature access
try:
    require_feature("pilot_mode")
    run_pilot_stats()
except FeatureNotEntitledError:
    print("Pro plan required")

Performance Optimization

from branchpy.performance import FileHashCache, ASTCache

hash_cache = FileHashCache()
ast_cache = ASTCache()

if not hash_cache.has_changed(file):
    ast = ast_cache.get(file)
else:
    ast = parser.parse_file(file)
    ast_cache.put(file, ast)

CLI Commands

Analysis

branchpy analyze /path/to/project
branchpy semantics2 flow script.rpy
branchpy media --missing -p /path/to/project

AI Features

branchpy ai review script.rpy
branchpy ai explain W001 script.rpy
branchpy ai refactor script.rpy --function main_menu
branchpy ai report --provider openai

Licensing

branchpy license login
branchpy license register
branchpy license claim-renpy
branchpy license status

QuickFix

branchpy quickfix inline script.rpy --var temp --line 42
branchpy quickfix extract script.rpy --line 42 --start 10 --end 45
branchpy quickfix fstring script.rpy

Performance

branchpy benchmark
branchpy cache clear
branchpy cache stats

VS Code Extension APIs

Commands

// Analysis
branchpy.analyze
branchpy.showCFG
branchpy.semantics.showRegistry

// AI Features
branchpy.ai.review
branchpy.ai.explain
branchpy.aiAutofix

// QuickFix
branchpy.quickfix.inlineVariable
branchpy.quickfix.extractVariable
branchpy.semantics.renameLabel

// Licensing
branchpy.license.login
branchpy.license.status

// Patch Engine
branchpy.showPatchPreview
branchpy.showPatchHistory
branchpy.showPatchTimeline

Language Features

  • Diagnostics: Semantic warnings in Problems panel
  • Code Actions: QuickFix operations in lightbulb menu
  • Hover: Warning explanations
  • Commands: All CLI commands via Command Palette

Performance Benchmarks

v1.1.1 Performance

Operation Time Improvement
AST Parse (1000 lines) 34ms 1.5x target
Propagation (100 labels) 4.54ms 440x target
Cache Hit 0.02ms 50x target
Media Scan (500 files, cached) 45ms 22x target
QuickFix Operation 5ms 2x target

Cache Performance

Cache Type Hit Rate Speedup
AST Cache 80% 239x
Media Cache 85% 19x
Analysis Cache 75% 50x

License Requirements

Feature Access by Plan

Feature Free Pro Ren’Py Team Enterprise
Basic Analysis ✅ ✅ ✅ ✅ ✅
Advanced Analysis ❌ ✅ ✅ ✅ ✅
AI Features ❌ ✅ ✅ ✅ ✅
Cloud Sync ❌ ❌ ❌ ✅ ✅
Team Features ❌ ❌ ❌ ✅ ✅
Federation ❌ ❌ ❌ ❌ ✅

API Versioning

Version Compatibility

  • v1.1.1: Current stable release (January 2026)
  • v1.0.0: Previous stable release
  • v0.9.x: Deprecated (compatibility mode)
  • v2.0.0: Planned (Q3 2026)

Breaking Changes

See CHANGELOG.md for breaking changes between versions.

Deprecation Policy

  • Deprecated APIs supported for 2 minor versions
  • Warning logs for deprecated usage
  • Migration guides provided

Getting Started

Installation

pip install branchpy

Quick Start

from branchpy.semantics import PythonASTParser
from branchpy.license import login, require_feature

# Login
login("user@example.com", "password")

# Check feature access
require_feature("analyze_advanced")

# Analyze code
parser = PythonASTParser()
ast = parser.parse_file("script.rpy")

print(f"Variables: {len(ast.variables)}")
print(f"Functions: {len(ast.functions)}")

Cross-References

Support

Source References:

  • Original API Documentation: docs/v1.1.0/API/README.md
  • Version: 1.1.1
  • Last Updated: January 23, 2026