Speconaut documentation

Start with your sources

Speconaut is an API tools platform. Speconaut AI is its first tool: a store-scoped knowledge API for questions, comparisons and follow-up conversations. Your sources remain the evidence; the index helps select which ones to read. Image, audio, conversion and document tools are planned separately, not available APIs in v1.

1. Prepare a Markdown source

   Create a clear file for each product or topic, including its identity and supported facts.

2. Publish the V3 index

   Save the source, then publish and verify the index. A successful upload alone does not make a product searchable.

3. Ask with source references

   Use the authorized store to ask a question and inspect the returned sources. See the request contract.

# Harbor Scarf
Product ID: harbor-scarf
Material: acrylic
Care: hand wash

Illustrative product data, not a shared catalog or a mandatory metadata format.

Four API capabilities

The workflow separates answering, missing information, source maintenance, and removal. Their availability is not the same.

Store boundaries

A store is a knowledge boundary for your product or topic collection, not a requirement to run a checkout. The design supports independent owners bringing their own sources, rather than everyone searching one shared catalog.

Retrieval is scoped to a configured store. A caller's product name, source label, or store slug is not authorization. Customer account-to-store ownership and role checks must be completed before general multi-tenant access opens.

Keep keys on your server. Do not substitute another store when your target is unavailable, and do not treat source text as an instruction to grant access or change system behavior.

Source files

RAW_TEXT is the authoritative source layer. Markdown is the simplest starting point; the current source-management preview also accepts JSON. Both have a 256 KiB upload limit per file.

• Include product identity, variants, relevant specifications, and the provenance of factual claims.
• Keep unknown facts unknown. Do not invent model codes, prices, availability, or release dates.
• Use evidence you are entitled to store. Do not include secrets or customer conversations in product files.
• Give different variants their own clear identity. A comparison is only as reliable as its selected sources.

The service is not limited to technology products. A scarf, a component, or another documented product can use the same source-backed approach. Source quality and coverage still determine what can be answered.

Retrieval & context

Directory V3 routes a query through bounded term and detail shards, then reads selected source files. It does not download the entire store's RAW_TEXT or a single complete product registry for each question.

The existing multilingual query planner interprets product questions. Previous conversation context can stay with a follow-up, while the current question still selects the relevant product evidence. Context is not a substitute for missing sources.

Source-management search is different: it performs a bounded metadata lookup without an AI call. An exact filename can also be checked in storage before index publication. Read the source-search limits.

Bounded reads control work per request; they do not establish million-product capacity. Incremental ingestion, routing growth, recall, and real large-store load testing remain development work.

Missing is a workflow, not an inventory verdict

A Missing record captures a product question or information gap that an owner wants to review. It does not prove that a product does not exist, is out of stock, or is unavailable for purchase.

1. Record the gap

   Add the question, notes, and an optional reference. Check existing source candidates before creating duplicate work.

2. Review and add evidence

   Prepare a source yourself or connect your own trusted workflow. Missing does not automatically invent or import product information.

3. Publish, verify, then resolve

   Verify that retrieval finds the intended source before marking the task resolved. Archive keeps the record; Reopen returns it to review.

The current store backlog is manual and paginated by UTC date. Connecting customer questions to this backlog automatically, with structured reasons and duplicate protection, is not yet enabled. A system outage must not become an ordinary missing-product record.

Data lifecycle

Saved

The source is in storage. The upload receipt can still say pending_directory_publish.

Published

A validated V3 build references the source. Check the active build and a representative product query.

Replaced

Replacement requires the observed revision. Re-publish and verify; do not blindly overwrite after a conflict.

Removed

Source deletion remains disabled until recovery safeguards are verified. Storage removal and index publication are separate operations.

These describe the lifecycle, not an existing automatic ingestion queue. A storage receipt, index publication, and successful answer retrieval are separate checks today.

AI tokens and Data API requests

Missing, Add/update and Delete do not run an AI layer. Their request processing uses validation and storage operations, not a language model. The current V3 publication builder also parses sources deterministically; it is a separate full-store job, not part of the upload fee.

These are proposed USD rates, not active deductions. One Missing list page is one request (up to 25 records); adding one file of up to 256 KiB is one request. The proposed fee is $0 for failed requests and verified replays. Durable replay protection is a launch prerequisite, not something a caller can claim in a payload.

Ask has a separate AI token tariff that includes actual planner and answer usage. A proposed $0.001 Ask minimum does not apply to Data API requests. Explicit calls to Ask and Missing are separate operations; a future internal Missing write must not silently become a second customer API request.

The conversation's planner may use AI to understand a question that lacks evidence. That is still Ask usage, not a new AI charge inside Missing. Future AI enrichment, classification or translation must be opt-in and separately metered.

Storage is proposed at $0.10 / GiB-month of retained bytes, including old versions and generated data, but no storage billing meter is active. Publication/reindexing and V3 search/check costs are separate and not priced for customer use yet. No unlimited storage, retention, or full-store rebuild is included. Read pricing and examples.

Availability & next steps

Directory V3 retrieval and the store workspace have local validation. The account adapter implements a controlled, explicitly configured store pilot. This documentation is not an announcement of general public API access.

Development preview. Before general customer launch: complete account-to-store authorization, ingestion and removal readiness, structured Missing events, idempotency, recovery, and measured quotas. The isolated local gateway validates usage deductions and safe request replay for its bound test owner; this does not activate the same policy on production. USD usage and wallet code remain subject to environment and pricing-policy configuration.

Continue to the API reference or open the store workspace. Workspace access depends on your environment and account permissions.