Skip to content

Public API Reference

This page documents the public API for using SpecSoloist as a library.

The primary entry point is SpecSoloistCore. Supporting types (BuildResult, SpecSoloistConfig, arrangement schema classes) are documented below.

For internal module details (resolvers, compilers, parsers), see Internals.

specsoloist

SpecSoloistCore

Main orchestrator for the SpecSoloist framework.

Coordinates spec parsing, code compilation, test generation, and the self-healing fix loop.

__init__ 

__init__(root_dir='.', api_key=None, config=None, event_bus=None)

Initialize SpecSoloistCore.

Parameters:

Name Type Description Default
root_dir str

Project root directory.

 '.'
api_key Optional[str]

LLM API key (deprecated, use config instead).

 None
config Optional[SpecSoloistConfig]

Full configuration object. If not provided, loads from environment variables.

 None
event_bus Optional[EventBus]

Optional event bus for build observability.

 None

list_specs 

list_specs()

List all available specification files.

read_spec 

read_spec(name)

Read the content of a specification file.

create_spec 

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

Create 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
type str

Component type ("function", "class", "module", "typedef").

 'function'

Returns:

Type Description
str

Success message with path to created file.

validate_spec 

validate_spec(name)

Validate a spec for basic structure and SRS compliance.

Returns:

Type Description
Dict[str, Any]

Dict with 'valid' (bool) and 'errors' (list) keys.

verify_project 

verify_project()

Verifies all specs in the project for strict schema compliance and dependency integrity.

Returns:

Type Description
Dict[str, Any]

Dict containing verification results per spec and global success status.

check_requirements 

check_requirements(specs=None)

Check that external packages declared in spec requires: fields are installed.

Parameters:

Name Type Description Default
specs Optional[List[str]]

List of spec names to check. If None, checks all specs.

 None

Returns:

Type Description
Dict[str, List[str]]

Dict mapping PEP 508 requirement string to list of spec names that need it,
Dict[str, List[str]]

for requirements that are NOT satisfied. Empty dict means all satisfied.

compile_spec 

compile_spec(name, model=None, skip_tests=False, arrangement=None)

Compile a spec to implementation code.

Parameters:

Name Type Description Default
name str

Spec filename (with or without .spec.md extension).

 required
model Optional[str]

Override the default LLM model (optional).

 None
skip_tests bool

If True, don't generate tests (default for typedef specs).

 False
arrangement Optional[Arrangement]

Optional build arrangement.

 None

Returns:

Type Description
str

Success message with path to generated code.

compile_tests 

compile_tests(name, model=None, arrangement=None)

Generate a test suite for a spec.

Parameters:

Name Type Description Default
name str

Spec filename (with or without .spec.md extension).

 required
model Optional[str]

Override the default LLM model (optional).

 None
arrangement Optional[Arrangement]

Optional build arrangement.

 None

Returns:

Type Description
str

Success message with path to generated tests.

compile_project 

compile_project(specs=None, model=None, generate_tests=True, incremental=False, parallel=False, max_workers=4, arrangement=None)

Compile multiple specs in dependency order.

This is the main entry point for building a project with interdependent specs.

Parameters:

Name Type Description Default
specs List[str]

List of spec names to compile. If None, compiles all specs.

 None
model Optional[str]

Override the default LLM model (optional).

 None
generate_tests bool

Whether to generate tests for non-typedef specs.

 True
incremental bool

If True, only recompile specs that have changed.

 False
parallel bool

If True, compile independent specs concurrently.

 False
max_workers int

Maximum number of parallel compilation workers.

 4
arrangement Optional[Arrangement]

Optional build arrangement.

 None

Returns:

Type Description
BuildResult

BuildResult with compilation status and details.

get_build_order 

get_build_order(specs=None)

Get the build order for specs without actually compiling.

Useful for previewing what would be built and in what order.

Parameters:

Name Type Description Default
specs List[str]

List of spec names. If None, includes all specs.

 None

Returns:

Type Description
List[str]

List of spec names in build order.

get_dependency_graph 

get_dependency_graph(specs=None)

Get the dependency graph for specs.

Parameters:

Name Type Description Default
specs List[str]

List of spec names. If None, includes all specs.

 None

Returns:

Type Description
DependencyGraph

DependencyGraph showing relationships between specs.

run_tests 

run_tests(name)

Run the tests for a specific component.

Returns:

Type Description
Dict[str, Any]

Dict with 'success' (bool) and 'output' (str) keys.

run_all_tests 

run_all_tests()

Run tests for all compiled specs.

Returns:

Type Description
Dict[str, Any]

Dict with overall 'success' and per-spec results.

attempt_fix 

attempt_fix(name, model=None, arrangement=None)

Attempt to fix a failing component.

Analyzes test output and rewrites either the code or tests to fix the failure.

Parameters:

Name Type Description Default
name str

Spec filename.

 required
model Optional[str]

Override the default LLM model (optional).

 None
arrangement Optional[Arrangement]

Optional build arrangement.

 None

Returns:

Type Description
str

Status message describing what was fixed.

BuildResult dataclass

Result of a multi-spec build operation.

Configuration

SpecSoloistConfig dataclass

Main configuration for the SpecSoloist framework.

__post_init__ 

__post_init__()

Compute derived absolute paths from root_dir.

from_env classmethod 

from_env(root_dir='.')

Load configuration from environment variables.

create_provider 

create_provider()

Create an LLM provider instance based on current config.

ensure_directories 

ensure_directories()

Create src and build directories if they don't exist.

Arrangement Schema

Arrangement

Bases: BaseModel

An Arrangement file bridges a Score (spec) to a specific Build Environment.

It defines how and where the code should be generated and verified.

ArrangementEnvironment

Bases: BaseModel

Environment settings for the build.

ArrangementOutputPaths

Bases: BaseModel

Output paths for implementation and tests, with optional per-spec overrides.

resolve_implementation 

resolve_implementation(name)

Return the implementation path for a spec, checking per-spec overrides first.

Parameters:

Name Type Description Default
name str

Spec identifier — may be a leaf name ("config") or a path ("subscribers/build_state"). Both {name} (leaf) and {path} (full relative) are available as pattern variables.

 required

resolve_tests 

resolve_tests(name)

Return the tests path for a spec, checking per-spec overrides first.

Parameters:

Name Type Description Default
name str

Spec identifier — may be a leaf name ("config") or a path ("subscribers/build_state"). Both {name} (leaf) and {path} (full relative) are available as pattern variables.

 required

ArrangementBuildCommands

Bases: BaseModel

Build, lint, and test commands.

ArrangementEnvVar

Bases: BaseModel

Declaration of a single environment variable expected by the project.

LLM Providers

LLMProvider

Bases: Protocol

Protocol defining the interface for LLM providers.

Any LLM provider (Gemini, Anthropic, OpenAI, local models, etc.) must implement this interface to be used with SpecSoloist.

generate 

generate(prompt, temperature=0.1, model=None)

Generate a response from the LLM.

Parameters:

Name Type Description Default
prompt str

The prompt to send to the LLM.

 required
temperature float

Sampling temperature (0.0 = deterministic, 1.0 = creative). Default is 0.1 for consistent code generation.

 0.1
model Optional[str]

Optional model override. If None, uses the provider's default model.

 None

Returns:

Type Description
LLMResponse

LLMResponse with generated text and optional token usage metadata.

Raises:

Type Description
RuntimeError

If the API call fails.

GeminiProvider

LLM provider for Google Gemini API.

Uses urllib for HTTP requests to avoid external dependencies.

__init__ 

__init__(api_key=None, model=DEFAULT_MODEL)

Initialize the Gemini provider.

Parameters:

Name Type Description Default
api_key Optional[str]

Google AI API key. Falls back to GEMINI_API_KEY env var.

 None
model str

Default model identifier (default: gemini-2.0-flash).

 DEFAULT_MODEL

generate 

generate(prompt, temperature=0.1, model=None)

Generate a response from Gemini.

Parameters:

Name Type Description Default
prompt str

The prompt to send.

 required
temperature float

Sampling temperature (0.0-1.0).

 0.1
model Optional[str]

Optional model override. If None, uses the default model.

 None

Returns:

Type Description
LLMResponse

LLMResponse with generated text and token usage.

Raises:

Type Description
RuntimeError

If the API call fails.

AnthropicProvider

LLM provider for Anthropic Claude API.

Uses urllib for HTTP requests to avoid external dependencies.

__init__ 

__init__(api_key=None, model=DEFAULT_MODEL, max_tokens=DEFAULT_MAX_TOKENS)

Initialize the Anthropic provider.

Parameters:

Name Type Description Default
api_key Optional[str]

Anthropic API key. Falls back to ANTHROPIC_API_KEY env var.

 None
model str

Default model identifier (default: claude-sonnet-4-20250514).

 DEFAULT_MODEL
max_tokens int

Maximum tokens in response (default: 8192).

 DEFAULT_MAX_TOKENS

generate 

generate(prompt, temperature=0.1, model=None)

Generate a response from Claude.

Parameters:

Name Type Description Default
prompt str

The prompt to send.

 required
temperature float

Sampling temperature (0.0-1.0).

 0.1
model Optional[str]

Optional model override. If None, uses the default model.

 None

Returns:

Type Description
LLMResponse

LLMResponse with generated text and token usage.

Raises:

Type Description
RuntimeError

If the API call fails.

PydanticAIProvider

LLM provider backed by pydantic-ai.

Supports Anthropic, OpenAI, Google Gemini, OpenRouter, and Ollama.

Provider strings recognized (SPECSOLOIST_LLM_PROVIDER): anthropic, gemini, google, openai, openrouter, ollama

Relevant env vars

ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY, OLLAMA_BASE_URL (default: http://localhost:11434)

__init__ 

__init__(provider='gemini', model=None, api_key=None)

Initialize the Pydantic AI provider.

Parameters:

Name Type Description Default
provider str

Provider name (anthropic, gemini, openai, openrouter, ollama).

 'gemini'
model Optional[str]

Default model identifier. Falls back to provider default.

 None
api_key Optional[str]

API key override. Falls back to appropriate env var.

 None

generate 

generate(prompt, temperature=0.1, model=None)

Generate a response using pydantic-ai.

Parameters:

Name Type Description Default
prompt str

The prompt to send to the LLM.

 required
temperature float

Sampling temperature (0.0-1.0). Default 0.1.

 0.1
model Optional[str]

Optional model override.

 None

Returns:

Type Description
LLMResponse

LLMResponse with generated text and token usage.

Raises:

Type Description
RuntimeError

If the API call fails or pydantic-ai is not installed.

spechestra

SpecConductor

Manages parallel builds.

Usage

conductor = SpecConductor("/path/to/project")

Build all specs

build_result = conductor.build()

__init__ 

__init__(project_dir, config=None, event_bus=None)

Initialize the conductor.

Parameters:

Name Type Description Default
project_dir str

Path to project root.

 required
config Optional[SpecSoloistConfig]

Optional configuration. Loads from env if not provided.

 None
event_bus Optional[EventBus]

Optional event bus for build observability.

 None

verify 

verify()

Verify all specs for schema compliance and interface compatibility.

Returns:

Type Description
VerifyResult

VerifyResult with per-spec verification details.

build 

build(specs=None, parallel=True, incremental=True, max_workers=4, arrangement=None, model=None)

Build specs in dependency order.

Parameters:

Name Type Description Default
specs Optional[List[str]]

List of spec names to build. If None, builds all specs.

 None
parallel bool

If True, compile independent specs concurrently.

 True
incremental bool

If True, only recompile changed specs.

 True
max_workers int

Maximum number of parallel workers.

 4
arrangement Optional[Arrangement]

Optional build arrangement.

 None
model Optional[str]

Optional LLM model override applied to all compilations.

 None

Returns:

Type Description
BuildResult

BuildResult with compilation status.

get_build_order 

get_build_order(specs=None)

Get the build order without actually building.

Parameters:

Name Type Description Default
specs Optional[List[str]]

List of spec names. If None, includes all specs.

 None

Returns:

Type Description
List[str]

List of spec names in build order.

get_dependency_graph 

get_dependency_graph(specs=None)

Get the dependency graph for visualization.

Parameters:

Name Type Description Default
specs Optional[List[str]]

List of spec names. If None, includes all specs.

 None

Returns:

Type Description
DependencyGraph

DependencyGraph showing relationships.