Internals Reference

This page documents SpecSoloist's internal modules. It is intended for contributors and agents working on the framework itself, not for library users.

For the public-facing API, see Public API.

---

Parser

SpecParser

Handles spec file discovery, reading, parsing, creation, and validation.

__init__

__init__(src_dir, template_dir=None)

Initialize the parser.

Parameters:

Name	Type	Description	Default
src_dir	str	Directory where spec files are stored.	required
template_dir	Optional[str]	Optional override for template location (for testing).	None

get_spec_path

get_spec_path(name)

Resolves a spec name to its full path.

list_specs

list_specs()

Lists all available specification files.

read_spec

read_spec(name)

Reads the raw content of a specification file.

spec_exists

spec_exists(name)

Checks if a spec file exists.

create_spec

create_spec(name, description, spec_type='function')

Creates a new specification file from the template.

Parameters:

Name	Type	Description	Default
name	str	Component name (e.g., "auth" creates "auth.spec.md").	required
description	str	Brief description of the component.	required
spec_type	str	Component type ("function", "type", "bundle", "module", "workflow").	'function'

Returns:

Type	Description
str	Path to the created spec file.

Raises:

Type	Description
FileExistsError	If the spec already exists.

parse_spec

parse_spec(name)

Parses a spec file into structured data.

validate_spec

validate_spec(name)

Validates a spec for basic structure based on its type.

Returns a dict with 'valid' bool and 'errors' list.

get_reference_warnings

get_reference_warnings(parsed)

Returns quality warnings for a reference spec (not errors).

extract_verification_snippet

extract_verification_snippet(body)

Extracts the code block from the '# Verification' section, if present.

get_module_name

get_module_name(name)

Extracts the module name from a spec filename.

parse_arrangement

parse_arrangement(content)

Parses an Arrangement from YAML or Markdown frontmatter.

load_global_context

load_global_context()

Loads the global context template for compilation prompts.

ParsedSpec dataclass

A fully parsed specification.

SpecMetadata dataclass

Parsed frontmatter from a spec file.

---

Compiler

SpecCompiler

Compiles specs to code using an LLM provider.

__init__

__init__(provider, global_context='', event_bus=None)

Initialize the compiler.

Parameters:

Name	Type	Description	Default
provider	LLMProvider	LLM provider used for code generation.	required
global_context	str	Optional project-level context injected into every prompt.	''
event_bus	Optional[EventBus]	Optional event bus for LLM call observability.	None

compile_code

compile_code(spec, model=None, arrangement=None, reference_specs=None)

Compiles a spec to implementation code.

Parameters:

Name	Type	Description	Default
spec	ParsedSpec	The parsed specification.	required
model	Optional[str]	Optional model override.	None
arrangement	Optional[Arrangement]	Optional build arrangement.	None
reference_specs	Optional[dict]	Optional dict of reference spec name to ParsedSpec, injected as context.	None

Returns:

Type	Description
str	The generated code.

compile_typedef

compile_typedef(spec, model=None, arrangement=None)

Compiles a typedef spec to type definitions (dataclasses, TypedDicts, etc.).

Parameters:

Name	Type	Description	Default
spec	ParsedSpec	The parsed specification (must be type: typedef).	required
model	Optional[str]	Optional model override.	None
arrangement	Optional[Arrangement]	Optional build arrangement.	None

Returns:

Type	Description
str	The generated type definition code.

compile_orchestrator

compile_orchestrator(spec, model=None, arrangement=None)

Compiles an orchestrator spec to workflow execution code.

Parameters:

Name	Type	Description	Default
spec	ParsedSpec	The parsed specification (must be type: orchestrator).	required
model	Optional[str]	Optional model override.	None
arrangement	Optional[Arrangement]	Optional build arrangement.	None

Returns:

Type	Description
str	The generated orchestration code.

compile_tests

compile_tests(spec, model=None, arrangement=None, reference_specs=None)

Generates a test suite for a spec.

Parameters:

Name	Type	Description	Default
spec	ParsedSpec	The parsed specification.	required
model	Optional[str]	Optional model override.	None
arrangement	Optional[Arrangement]	Optional build arrangement.	None
reference_specs	Optional[dict]	Optional dict of reference spec name to ParsedSpec, injected as context.	None

Returns:

Type	Description
str	The generated test code.

generate_fix

generate_fix(spec, code_content, test_content, error_log, model=None, arrangement=None)

Generates a fix for failing tests.

Parameters:

Name	Type	Description	Default
spec	ParsedSpec	The parsed specification (source of truth).	required
code_content	str	Current implementation code.	required
test_content	str	Current test code.	required
error_log	str	Test failure output.	required
model	Optional[str]	Optional model override.	None
arrangement	Optional[Arrangement]	Optional build arrangement.	None

Returns:

Type	Description
str	The raw LLM response with FILE markers.

parse_fix_response

parse_fix_response(response)

Parses the fix response to extract file contents.

Returns a dict mapping filename -> content.

---

Runner

TestRunner

Handles execution of tests for different languages.

__init__

__init__(build_dir, config=None)

Initialize the test runner.

Parameters:

Name	Type	Description	Default
build_dir	str	Directory where code and tests are built.	required
config	Optional[SpecSoloistConfig]	SpecSoloist configuration.	None

get_test_path

get_test_path(module_name, language='python')

Returns the path to the test file for a module.

get_code_path

get_code_path(module_name, language='python')

Returns the path to the implementation file for a module.

test_exists

test_exists(module_name, language='python')

Checks if a test file exists for the module.

code_exists

code_exists(module_name, language='python')

Checks if an implementation file exists for the module.

read_code

read_code(module_name, language='python')

Reads the implementation file content.

read_tests

read_tests(module_name, language='python')

Reads the test file content.

write_code

write_code(module_name, content, language='python')

Writes implementation code to the build directory.

write_tests

write_tests(module_name, content, language='python')

Writes test code to the build directory.

read_file

read_file(filename)

Reads a file relative to the build directory.

write_file

write_file(filename, content)

Writes a file to a specific path.

If filename is relative, it's relative to build_dir.

run_tests

run_tests(module_name, language='python')

Runs the test command for a module based on its language configuration.

run_custom_test

run_custom_test(command)

Runs a custom test command (shell).

TestResult dataclass

Result of a test run.

---

Dependency Resolver

DependencyResolver

Resolves dependencies between specs and computes build orders.

__init__

__init__(parser)

Initialize the resolver.

Parameters:

Name	Type	Description	Default
parser	SpecParser	SpecParser used to read spec frontmatter and list specs.	required

build_graph

build_graph(spec_names=None)

Build a DependencyGraph from spec frontmatter.

Parameters:

Name	Type	Description	Default
spec_names	List[str]	Specs to include. Defaults to all specs in the src directory.	None

Returns:

Type	Description
DependencyGraph	DependencyGraph with all dependency relationships populated.

Raises:

Type	Description
MissingDependencyError	If a spec depends on a name that doesn't exist.

resolve_build_order

resolve_build_order(spec_names=None)

Return a linear build order with dependencies before dependents.

Raises:

Type	Description
CircularDependencyError	If specs form a dependency cycle.

get_parallel_build_order

get_parallel_build_order(spec_names=None)

Return specs grouped into parallel build levels.

Each level is a list of specs that can be compiled concurrently because all their dependencies appear in earlier levels.

get_affected_specs

get_affected_specs(changed_spec, graph=None)

Return all specs that transitively depend on changed_spec, in build order.

Parameters:

Name	Type	Description	Default
changed_spec	str	The spec that changed.	required
graph	DependencyGraph	Pre-built dependency graph. Built from all specs if not provided.	None

DependencyGraph dataclass

Represents dependency relationships between specs.

add_spec

add_spec(name, depends_on=None)

Register a spec and its dependencies in the graph.

Parameters:

Name	Type	Description	Default
name	str	Spec name to register.	required
depends_on	List[str]	List of spec names this spec depends on.	None

get_dependencies

get_dependencies(name)

Return the list of specs that the given spec depends on.

get_dependents

get_dependents(name)

Return the list of specs that depend on the given spec.

CircularDependencyError

Bases: Exception

Raised when specs form a dependency cycle.

__init__

__init__(cycle)

Initialize with the detected cycle path.

Parameters:

Name	Type	Description	Default
cycle	List[str]	Ordered list of spec names forming the cycle.	required

MissingDependencyError

Bases: Exception

Raised when a spec depends on one that doesn't exist.

__init__

__init__(spec, missing)

Initialize with the spec and the missing dependency name.

Parameters:

Name	Type	Description	Default
spec	str	Name of the spec that has an unresolvable dependency.	required
missing	str	Name of the dependency that could not be found.	required

---

Build Manifest

BuildManifest dataclass

Collection of build records, persisted as JSON.

get_spec_info

get_spec_info(name)

Return the build record for a spec, or None if not yet built.

update_spec

update_spec(name, spec_hash, dependencies, output_files)

Record a successful build for a spec, stamped with the current UTC time.

remove_spec

remove_spec(name)

Remove a spec's build record from the manifest (no-op if absent).

save

save(build_dir)

Persist the manifest to JSON in build_dir.

load classmethod

load(build_dir)

Load the manifest from build_dir, returning an empty manifest if missing or corrupt.

IncrementalBuilder

Determines which specs need rebuilding.

__init__

__init__(manifest, src_dir)

Initialize the incremental builder.

Parameters:

Name	Type	Description	Default
manifest	BuildManifest	The current build manifest recording previous compilation state.	required
src_dir	str	Path to the directory containing spec files.	required

needs_rebuild

needs_rebuild(spec_name, current_hash, current_deps, rebuilt_specs)

Return True if a spec needs to be recompiled.

Parameters:

Name	Type	Description	Default
spec_name	str	Name of the spec to check.	required
current_hash	str	SHA-256 hash of the current spec file content.	required
current_deps	List[str]	Current list of dependency names from the spec.	required
rebuilt_specs	set	Set of spec names already rebuilt in this run.	required

get_rebuild_plan

get_rebuild_plan(build_order, spec_hashes, spec_deps)

Return the ordered subset of specs that need rebuilding.

Parameters:

Name	Type	Description	Default
build_order	List[str]	Full topological build order for all specs.	required
spec_hashes	Dict[str, str]	Mapping of spec name to current content hash.	required
spec_deps	Dict[str, List[str]]	Mapping of spec name to current dependency list.	required

SpecBuildInfo dataclass

Build record for a single spec.

to_dict

to_dict()

Serialize to a JSON-compatible dict.

from_dict classmethod

from_dict(data)

Deserialize from a dict produced by to_dict.

---

Spec Drift Detection

SpecDiffResult dataclass

Result of comparing a spec against its compiled code.

issue_count property

issue_count

Total number of drift issues found.

to_dict

to_dict()

Serialize to a JSON-compatible dict.

SpecDiffIssue dataclass

A single drift issue found by spec_diff.

---

Respec

Respecer

Reverse engineers Python source code into SpecSoloist specifications.

This is the fallback implementation used when --no-agent is specified. The preferred approach is agent-first (see score/prompts/respec.md).

__init__

__init__(config=None, provider=None)

Initialize the Respecer.

Parameters:

Name	Type	Description	Default
config	Optional[SpecSoloistConfig]	Framework configuration. Defaults to config from environment.	None
provider	Optional[LLMProvider]	LLM provider. Defaults to the provider configured in config.	None

respec

respec(source_path, test_path=None, model=None)

Generate a spec from source code (single-shot LLM call).