Skip to content

API_SPECIFICATION.md

Latest commit

 

History

History
308 lines (250 loc) · 11.5 KB

API_SPECIFICATION.md

File metadata and controls

308 lines (250 loc) · 11.5 KB

FPF Module API Specification

Version: v1.2.3 | Status: Active | Last Updated: March 2026

Overview

This document provides detailed API specifications for the FPF module, including all public classes, methods, and their signatures.

High-Level API: FPFClient

Class: FPFClient

Convenient high-level interface for working with FPF specifications.

class FPFClient:
    def __init__(self, spec_path: str = None)
    def load_from_file(self, file_path: str) -> FPFSpec
    def fetch_and_load(self, repo: str = "ailev/FPF", branch: str = "main") -> FPFSpec
    def search(self, query: str, filters: dict = None) -> list[Pattern]
    def get_pattern(self, pattern_id: str) -> Pattern
    def export_json(self, output_path: str) -> None
    def build_context(self, pattern_id: str = None, filters: dict = None) -> str

Methods

load_from_file(file_path: str) -> FPFSpec

  • Load and parse FPF specification from a local file
  • Parameters: file_path - Path to FPF-Spec.md file
  • Returns: Parsed FPFSpec object
  • Raises: FileNotFoundError if file doesn't exist, ValueError on parse errors

fetch_and_load(repo: str, branch: str) -> FPFSpec

  • Fetch latest FPF specification from GitHub and load it
  • Parameters:
    • repo - GitHub repository (default: "ailev/FPF")
    • branch - Branch name (default: "main")
  • Returns: Parsed FPFSpec object
  • Raises: requests.RequestException on network errors

search(query: str, filters: dict = None) -> list[Pattern]

  • Search for patterns
  • Parameters:
    • query - Search query string
    • filters - Optional filters (status, part, etc.)
  • Returns: List of matching Pattern objects
  • Raises: ValueError if no specification loaded

get_pattern(pattern_id: str) -> Pattern

  • Get a pattern by ID
  • Parameters: pattern_id - Pattern identifier (e.g., "A.1")
  • Returns: Pattern object
  • Raises: ValueError if pattern not found or no spec loaded

export_json(output_path: str) -> None

  • Export the specification to JSON
  • Parameters: output_path - Path to output JSON file
  • Raises: ValueError if no specification loaded

build_context(pattern_id: str = None, filters: dict = None) -> str

  • Build context string for prompt engineering
  • Parameters:
    • pattern_id - Optional pattern ID to build context for
    • filters - Optional filters for context building
  • Returns: Context string
  • Raises: ValueError if no specification loaded

Core Components

FPFParser

class FPFParser:
    def parse_spec(self, markdown_content: str, source_path: str = None) -> FPFSpec
    def extract_table_of_contents(self, content: str) -> Dict[str, any]
    def extract_patterns(self, content: str) -> List[Pattern]
    def extract_sections(self, pattern_content: str) -> Dict[str, str]

FPFExtractor

class FPFExtractor:
    def extract_patterns(self, spec: FPFSpec) -> List[Pattern]
    def extract_concepts(self, spec: FPFSpec) -> List[Concept]
    def extract_relationships(self, spec: FPFSpec) -> List[Relationship]
    def extract_keywords(self, spec: FPFSpec) -> Dict[str, List[str]]
    def extract_dependencies(self, spec: FPFSpec) -> Dict[str, Dict[str, List[str]]]

FPFIndexer

class FPFIndexer:
    def build_index(self, spec: FPFSpec) -> FPFIndex
    def search_patterns(self, query: str, filters: Dict[str, Any] = None) -> List[Pattern]
    def get_pattern_by_id(self, pattern_id: str) -> Optional[Pattern]
    def get_related_patterns(self, pattern_id: str, depth: int = 1) -> List[Pattern]

FPFFetcher

class FPFFetcher:
    def __init__(self, cache_dir: Path = None)
    def fetch_latest(self, repo: str = "ailev/FPF", branch: str = "main", file_path: str = "FPF-Spec.md") -> str
    def check_for_updates(self, local_path: Path) -> bool
    def get_version_info(self, repo: str = "ailev/FPF") -> Dict[str, any]
    def cache_spec(self, content: str, version: str = None) -> Path

FPFExporter

class FPFExporter:
    def export_json(self, spec: FPFSpec, output_path: Path) -> None
    def export_patterns_json(self, patterns: List[Pattern], output_path: Path) -> None
    def export_concepts_json(self, concepts: List[Concept], output_path: Path) -> None
    def export_for_context(self, spec: FPFSpec, filters: Dict[str, Any] = None) -> Dict[str, Any]

FPFVisualizer

class FPFVisualizer:
    def visualize_pattern_hierarchy(self, patterns: List[Pattern]) -> str
    def visualize_dependencies(self, patterns: List[Pattern]) -> str
    def generate_report(self, spec: FPFSpec, output_path: Path) -> None
    def create_pattern_card(self, pattern: Pattern) -> str

ContextBuilder

class ContextBuilder:
    def __init__(self, spec: FPFSpec)
    def build_context_for_pattern(self, pattern_id: str, depth: int = 1, include_related: bool = True) -> str
    def build_context_for_concept(self, concept: str) -> str
    def build_minimal_context(self, filters: Dict[str, Any] = None) -> str
    def build_full_context(self) -> str

TermAnalyzer

class TermAnalyzer:
    def extract_terms_from_pattern(self, pattern: Pattern) -> Set[str]
    def build_term_cooccurrence_matrix(self, spec: FPFSpec) -> Dict[str, Dict[str, int]]
    def get_shared_terms(self, spec: FPFSpec, min_occurrences: int = 2) -> List[Tuple[str, int, List[str]]]
    def get_term_frequency(self, spec: FPFSpec) -> Dict[str, int]
    def get_important_terms(self, spec: FPFSpec, top_n: int = 50) -> List[Tuple[str, int, float]]
    def analyze_section_terms(self, spec: FPFSpec, part: str = None) -> Dict[str, List[str]]
    def find_cross_section_terms(self, spec: FPFSpec, min_sections: int = 2) -> List[Tuple[str, int, List[str]]]

GraphGenerator

class GraphGenerator:
    def __init__(self, figsize: Tuple[int, int] = (12, 8), dpi: int = 300)
    def create_pattern_dependency_graph(self, spec: FPFSpec, layout: str = "hierarchical") -> nx.DiGraph
    def create_term_cooccurrence_graph(self, cooccurrence: Dict[str, Dict[str, int]], min_weight: int = 2) -> nx.Graph
    def create_concept_relationship_graph(self, spec: FPFSpec) -> nx.Graph
    def apply_hierarchical_layout(self, G: nx.DiGraph) -> Dict[str, Tuple[float, float]]
    def apply_force_directed_layout(self, G: nx.Graph, k: float = None, iterations: int = 50) -> Dict[str, Tuple[float, float]]
    def apply_circular_layout(self, G: nx.Graph) -> Dict[str, Tuple[float, float]]
    def apply_tree_layout(self, G: nx.Graph, root: str = None) -> Dict[str, Tuple[float, float]]
    def get_node_colors_by_attribute(self, G: nx.Graph, attribute: str, color_map: Dict[str, str] = None) -> List[str]
    def get_node_sizes_by_importance(self, G: nx.Graph, importance_metric: str = "degree") -> List[float]

FPFVisualizerPNG

class FPFVisualizerPNG:
    def __init__(self, figsize: Tuple[int, int] = (16, 12), dpi: int = 300)
    def visualize_shared_terms_network(self, spec: FPFSpec, output_path: Path, min_weight: int = 2, top_n: int = 100) -> None
    def visualize_pattern_dependencies(self, spec: FPFSpec, output_path: Path, layout: str = "hierarchical", color_by: str = "status") -> None
    def visualize_concept_map(self, spec: FPFSpec, output_path: Path, layout: str = "circular") -> None
    def visualize_part_hierarchy(self, spec: FPFSpec, output_path: Path) -> None
    def visualize_status_distribution(self, spec: FPFSpec, output_path: Path, chart_type: str = "bar") -> None

SectionManager

class SectionManager:
    def __init__(self, spec: FPFSpec)
    def extract_part(self, part_id: str) -> Dict[str, any]
    def extract_pattern_group(self, pattern_ids: List[str], include_dependencies: bool = True) -> Dict[str, any]
    def extract_concept_cluster(self, concept_names: List[str], include_related_patterns: bool = True) -> Dict[str, any]
    def extract_relationship_subset(self, relationship_types: List[str], include_patterns: bool = True) -> Dict[str, any]
    def list_parts(self) -> List[str]
    def list_pattern_groups(self, by_part: bool = False) -> Dict[str, List[str]]
    def get_section_statistics(self) -> Dict[str, any]

SectionExporter

class SectionExporter:
    def __init__(self, section_manager: SectionManager)
    def export_part(self, part_id: str, output_path: Path, include_metadata: bool = True) -> None
    def export_pattern_group(self, pattern_ids: List[str], output_path: Path, include_dependencies: bool = True, include_metadata: bool = True) -> None
    def export_single_pattern(self, pattern_id: str, output_path: Path, include_related: bool = False) -> None
    def export_concept_cluster(self, concept_names: List[str], output_path: Path, include_related_patterns: bool = True, include_metadata: bool = True) -> None
    def export_all_parts(self, output_dir: Path, include_metadata: bool = True) -> List[Path]

SectionImporter

class SectionImporter:
    def __init__(self, base_spec: Optional[FPFSpec] = None)
    def import_part(self, json_path: Path) -> FPFSpec
    def import_pattern_group(self, json_path: Path) -> FPFSpec
    def import_single_pattern(self, json_path: Path) -> FPFSpec
    def merge_specs(self, *specs: FPFSpec) -> FPFSpec

FPFAnalyzer

class FPFAnalyzer:
    def __init__(self, spec: FPFSpec)
    def calculate_pattern_importance(self) -> Dict[str, float]
    def calculate_concept_centrality(self) -> Dict[str, float]
    def calculate_relationship_strength(self) -> Dict[Tuple[str, str, str], float]
    def analyze_dependency_depth(self) -> Dict[str, int]
    def get_critical_patterns(self, top_n: int = 10) -> List[Tuple[str, float]]
    def get_isolated_patterns(self) -> List[str]
    def analyze_part_cohesion(self) -> Dict[str, float]
    def get_analysis_summary(self) -> Dict[str, any]

ReportGenerator

class ReportGenerator:
    def __init__(self, spec: FPFSpec)
    def generate_html_report(self, output_path: Path, include_analysis: bool = True) -> None

Data Models

See models.py for complete Pydantic model definitions.

Pattern

  • id: str
  • title: str
  • status: PatternStatus (enum: Stable, Draft, Stub, New)
  • keywords: List[str]
  • search_queries: List[str]
  • dependencies: Dict[str, List[str]]
  • sections: Dict[str, str]
  • content: str
  • metadata: Dict[str, Any]
  • part: Optional[str]
  • cluster: Optional[str]

Concept

  • name: str
  • definition: str
  • pattern_id: str
  • type: ConceptType (enum: U_TYPE, MECHANISM, ARCHITHEORY, etc.)
  • references: List[str]
  • aliases: List[str]
  • metadata: Dict[str, Any]

Relationship

  • source: str
  • target: str
  • type: RelationshipType (enum: BUILDS_ON, PREREQUISITE_FOR, etc.)
  • strength: Optional[str]
  • description: Optional[str]
  • metadata: Dict[str, Any]

FPFSpec

  • version: Optional[str]
  • last_updated: Optional[datetime]
  • source_url: Optional[str]
  • source_hash: Optional[str]
  • patterns: List[Pattern]
  • concepts: List[Concept]
  • relationships: List[Relationship]
  • table_of_contents: Dict[str, Any]
  • metadata: Dict[str, Any]

Error Handling

All methods may raise:

  • ValueError - Invalid input or missing data
  • FileNotFoundError - File not found
  • requests.RequestException - Network errors (fetcher only)
  • KeyError - Missing keys in dictionaries

Examples

See README.md for usage examples.

Navigation Links