Python SDK

pip install predev-api

from predev_api import PredevAPI

# Initialize the predev client with your API key
predev = PredevAPI(api_key="your_api_key_here")

# Generate a fast specification
result = predev.fast_spec(
    input_text="Build a task management app with team collaboration"
)

print(result)

predev = PredevAPI(api_key="your_api_key")

result = predev.fast_spec(
    input_text="Build a SaaS project management tool with real-time collaboration",
    current_context=None,  # Optional: existing project context
    doc_urls=None  # Optional: documentation URLs to reference
)

result = predev.fast_spec(
    input_text="Build a SaaS project management tool with real-time collaboration"
)

result = predev.deep_spec(
    input_text="Build a healthcare platform with HIPAA compliance",
    current_context=None,  # Optional: existing project context
    doc_urls=None  # Optional: documentation URLs
)

result = predev.deep_spec(
    input_text="Build a healthcare platform with HIPAA compliance"
)

result = predev.fast_spec_async(
    input_text="Build a comprehensive e-commerce platform"
)
# Returns: AsyncResponse(specId="spec_123", status="pending")

result = predev.deep_spec_async(
    input_text="Build a fintech platform with regulatory compliance"
)
# Returns: AsyncResponse(specId="spec_456", status="pending")

status = predev.get_spec_status("spec_123")
# Returns SpecResponse with status: "pending" | "processing" | "completed" | "failed"

status = predev.get_spec_status("spec_123")
# Returns SpecResponse with status: "pending" | "processing" | "completed" | "failed"

balance = predev.get_credits_balance()
# Returns: CreditsBalanceResponse(success=True, creditsRemaining=450)

balance = predev.get_credits_balance()
if balance.creditsRemaining < 50:
    print(f"Low credits: {balance.creditsRemaining} remaining")
else:
    print(f"Credits available: {balance.creditsRemaining}")

# Get first 20 specs
result = predev.list_specs()

# Get completed specs only
completed = predev.list_specs(status='completed')

# Paginate: get specs 20-40
page2 = predev.list_specs(skip=20, limit=20)

# Filter by endpoint type
fast_specs = predev.list_specs(endpoint='fast_spec')

# Search for "payment" specs
payment_specs = predev.find_specs(query='payment')

# Search for specs starting with "Build"
build_specs = predev.find_specs(query='^Build')

# Search: only completed specs mentioning "auth"
auth_specs = predev.find_specs(
    query='auth',
    status='completed'
)

# Complex regex: find SaaS or SASS projects
saas_specs = predev.find_specs(query='saas|sass')

from predev_api import PredevAPI

predev = PredevAPI(api_key="your_api_key")

# Just pass the file path as a string
result = predev.fast_spec(
    input_text="Generate specs based on these requirements",
    file="path/to/requirements.pdf"
)

# Open and upload a file
with open("architecture.doc", "rb") as f:
    result = predev.deep_spec(
        input_text="Create comprehensive specs",
        file=f
    )

# Or pass a file-like object
from io import BytesIO

file_content = BytesIO(b"Design specifications...")
result = predev.fast_spec(
    input_text="Generate specs",
    file=file_content
)

result = predev.fast_spec(
    input_text="Based on the design document",
    file="design.pdf"
)

print(result.uploadedFileName)       # "design.pdf"
print(result.uploadedFileShortUrl)   # "https://api.pre.dev/f/xyz123"
print(result.codingAgentSpecUrl)     # Spec for AI systems
print(result.humanSpecUrl)           # Spec for humans

@dataclass
class AsyncResponse:
    specId: str                                    # Unique ID for polling (e.g., "spec_abc123")
    status: Literal['pending', 'processing', 'completed', 'failed']

@dataclass
class SpecResponse:
    # Basic info
    _id: Optional[str] = None                      # Internal ID
    created: Optional[str] = None                  # ISO timestamp
    endpoint: Optional[Literal['fast_spec', 'deep_spec']] = None
    input: Optional[str] = None                    # Original input text
    status: Optional[Literal['pending', 'processing', 'completed', 'failed']] = None
    success: Optional[bool] = None

    # Output data (when completed)
    uploadedFileShortUrl: Optional[str] = None    # URL to input file
    uploadedFileName: Optional[str] = None        # Name of input file
    humanSpecUrl: Optional[str] = None            # URL to human-readable spec
    humanSpecMarkdown: Optional[str] = None       # Full markdown SOW for humans/clients
    humanSpecJson: Optional['HumanSpecJson'] = None   # Full structured SOW JSON
    totalHumanHours: Optional[float] = None       # Estimated hours for human implementation
    codingAgentSpecUrl: Optional[str] = None          # URL to coding agent spec format
    codingAgentSpecMarkdown: Optional[str] = None     # Simplified markdown SOW for AI tools
    codingAgentSpecJson: Optional['CodingAgentSpecJson'] = None  # Structured SOW JSON for AI tools
    executionTime: Optional[int] = None           # Processing time in milliseconds

    # Integration URLs (when completed)
    predevUrl: Optional[str] = None               # Link to pre.dev project
    lovableUrl: Optional[str] = None              # Link to generate with Lovable
    cursorUrl: Optional[str] = None               # Link to generate with Cursor
    v0Url: Optional[str] = None                   # Link to generate with v0
    boltUrl: Optional[str] = None                 # Link to generate with Bolt

    # Error handling
    errorMessage: Optional[str] = None            # Error details if failed
    progress: Optional[int] = None                # Overall progress percentage (0-100)
    progressMessage: Optional[str] = None         # Detailed progress message (e.g., "Generating User Stories...")


@dataclass
class CodingAgentSpecJson:
    title: Optional[str] = None
    executiveSummary: Optional[str] = None
    coreFunctionalities: Optional[List['SpecCoreFunctionality']] = None
    techStack: Optional[List['SpecTechStackItem']] = None
    techStackGrouped: Optional[dict] = None
    milestones: Optional[List['CodingAgentMilestone']] = None


@dataclass
class CodingAgentMilestone:
    milestoneNumber: int = 0
    description: str = ''
    stories: List['CodingAgentStory'] = None


@dataclass
class CodingAgentStory:
    id: Optional[str] = None
    title: str = ''
    description: Optional[str] = None
    acceptanceCriteria: Optional[List[str]] = None
    complexity: Optional[str] = None
    subTasks: List['CodingAgentSubTask'] = None


@dataclass
class CodingAgentSubTask:
    id: Optional[str] = None
    description: str = ''
    complexity: str = ''


@dataclass
class HumanSpecJson:
    title: Optional[str] = None
    executiveSummary: Optional[str] = None
    coreFunctionalities: Optional[List['SpecCoreFunctionality']] = None
    personas: Optional[List['SpecPersona']] = None
    techStack: Optional[List['SpecTechStackItem']] = None
    techStackGrouped: Optional[dict] = None
    milestones: Optional[List['HumanSpecMilestone']] = None
    totalHours: Optional[float] = None
    roles: Optional[List['SpecRole']] = None


@dataclass
class HumanSpecMilestone:
    milestoneNumber: int = 0
    description: str = ''
    hours: float = 0.0
    stories: List['HumanSpecStory'] = None


@dataclass
class HumanSpecStory:
    id: Optional[str] = None
    title: str = ''
    description: Optional[str] = None
    acceptanceCriteria: Optional[List[str]] = None
    hours: float = 0.0
    complexity: Optional[str] = None
    subTasks: List['HumanSpecSubTask'] = None


@dataclass
class HumanSpecSubTask:
    id: Optional[str] = None
    description: str = ''
    hours: float = 0.0
    complexity: str = ''
    roles: Optional[List['SpecRole']] = None


@dataclass
class SpecPersona:
    title: str = ''
    description: str = ''
    primaryGoals: Optional[List[str]] = None
    painPoints: Optional[List[str]] = None
    keyTasks: Optional[List[str]] = None


@dataclass
class SpecRole:
    name: str = ''
    shortHand: str = ''


@dataclass
class SpecCoreFunctionality:
    name: str = ''
    description: str = ''
    priority: Optional[str] = None  # "High" | "Medium" | "Low"


@dataclass
class SpecTechStackItem:
    name: str = ''
    category: str = ''

@dataclass
class ListSpecsResponse:
    specs: List[SpecResponse]  # Array of spec objects
    total: int                 # Total count of matching specs
    hasMore: bool              # Whether more results are available

@dataclass
class CreditsBalanceResponse:
    success: bool
    creditsRemaining: int

from predev_api import PredevAPI

predev = PredevAPI(api_key="your_api_key")

# Find all payment-related specs
payment_specs = predev.find_specs(query='payment')
print(f"Found {payment_specs.total} payment specs")

# Find specs starting with "Build"
build_specs = predev.find_specs(query='^Build')

# Find completed authentication specs
auth_specs = predev.find_specs(
    query='auth',
    status='completed',
    endpoint='deep_spec'
)

# Complex search: SaaS or SASS projects
saas_specs = predev.find_specs(query='saas|sass')
for spec in saas_specs.specs:
    print(f"Found: {spec.input}")

from predev_api import PredevAPI

predev = PredevAPI(api_key="your_api_key")

# Get current credit balance
balance = predev.get_credits_balance()
print(f"Credits remaining: {balance.creditsRemaining}")

# Check before making expensive request
if balance.creditsRemaining >= 50:
    result = predev.deep_spec(
        input_text="Build an enterprise platform"
    )
else:
    print(f"Insufficient credits. Need 50, have {balance.creditsRemaining}")