synth-ai 0.20.2.dev643__tar.gz → 0.21.0.dev647__tar.gz

{synth_ai-0.20.2.dev643/synth_ai.egg-info → synth_ai-0.21.0.dev647}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synth-ai
-Version: 0.20.2.dev643
+Version: 0.21.0.dev647
 Summary: Python SDK and CLI for Synth Index, Managed Research, and Research Factory
 Author-email: Synth AI <josh@usesynth.ai>
 License-Expression: MIT
@@ -29,7 +29,7 @@ Dynamic: license-file
 
 # Synth AI SDK
 
-<!-- CI release pins: PyPI-0.20.0-orange synth-ai==0.20.0 -->
+<!-- CI release pins: PyPI-0.21.0-orange synth-ai==0.21.0 -->
 
 [![PyPI version](https://img.shields.io/pypi/v/synth-ai.svg)](https://pypi.org/project/synth-ai/)
 [![License](https://img.shields.io/pypi/l/synth-ai.svg)](https://pypi.org/project/synth-ai/)
@@ -202,6 +202,29 @@ synth-ai --help
 synth-ai research --help
 ```
 
+## Synth Index (alpha v0.1)
+
+Synth Index alpha v0.1 offers authenticated, paid FAST and DEEP Search over
+reviewed, published research. DEEP is in beta. Install `synth-ai>=0.20.2`:
+
+```bash
+uv add "synth-ai>=0.20.2"
+```
+
+- **Python:** `SynthClient().index.search(query=..., mode="fast" | "deep", billing=...)`.
+  An example is under [Public Surface](#public-surface). The
+  [Index SDK guide](synth_ai/sdk/index/README.md) covers DEEP's durable Search
+  ID, reconnect and cancel.
+- **MCP:** `synth-ai-index-mcp` is an Index-only stdio server and is read-only
+  by default. Search tools are advertised only when `SYNTH_API_KEY` is set.
+  Setup is in the [Index SDK guide](synth_ai/sdk/index/README.md#external-agents-over-stdio-mcp).
+- Every Search needs an API key, an authorized organization and funding.
+
+Not in alpha v0.1: `/index/answer`, downloading the files behind
+a citation, citations that point to an exact passage, a latency guarantee, and
+free, anonymous or zero-data-retention Search. Contributing research to the
+Index is planned for Index v0.2.
+
 ## Public Surface
 
 Use `SynthClient` as the front door:

{synth_ai-0.20.2.dev643 → synth_ai-0.21.0.dev647}/README.md

@@ -1,6 +1,6 @@
 # Synth AI SDK
 
-<!-- CI release pins: PyPI-0.20.0-orange synth-ai==0.20.0 -->
+<!-- CI release pins: PyPI-0.21.0-orange synth-ai==0.21.0 -->
 
 [![PyPI version](https://img.shields.io/pypi/v/synth-ai.svg)](https://pypi.org/project/synth-ai/)
 [![License](https://img.shields.io/pypi/l/synth-ai.svg)](https://pypi.org/project/synth-ai/)
@@ -173,6 +173,29 @@ synth-ai --help
 synth-ai research --help
 ```
 
+## Synth Index (alpha v0.1)
+
+Synth Index alpha v0.1 offers authenticated, paid FAST and DEEP Search over
+reviewed, published research. DEEP is in beta. Install `synth-ai>=0.20.2`:
+
+```bash
+uv add "synth-ai>=0.20.2"
+```
+
+- **Python:** `SynthClient().index.search(query=..., mode="fast" | "deep", billing=...)`.
+  An example is under [Public Surface](#public-surface). The
+  [Index SDK guide](synth_ai/sdk/index/README.md) covers DEEP's durable Search
+  ID, reconnect and cancel.
+- **MCP:** `synth-ai-index-mcp` is an Index-only stdio server and is read-only
+  by default. Search tools are advertised only when `SYNTH_API_KEY` is set.
+  Setup is in the [Index SDK guide](synth_ai/sdk/index/README.md#external-agents-over-stdio-mcp).
+- Every Search needs an API key, an authorized organization and funding.
+
+Not in alpha v0.1: `/index/answer`, downloading the files behind
+a citation, citations that point to an exact passage, a latency guarantee, and
+free, anonymous or zero-data-retention Search. Contributing research to the
+Index is planned for Index v0.2.
+
 ## Public Surface
 
 Use `SynthClient` as the front door:

{synth_ai-0.20.2.dev643 → synth_ai-0.21.0.dev647}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "synth-ai"
-version = "0.20.2.dev643"
+version = "0.21.0.dev647"
 description = "Python SDK and CLI for Synth Index, Managed Research, and Research Factory"
 authors = [{name = "Synth AI", email = "josh@usesynth.ai"}]
 license = "MIT"

{synth_ai-0.20.2.dev643 → synth_ai-0.21.0.dev647}/synth_ai/cli/research_projects.py

@@ -368,6 +368,7 @@ def workspace_upload(
         ProjectId,
         WorkspaceFileEncoding,
         WorkspaceFileKind,
+        WorkspaceFileMode,
         WorkspaceFilesBatchUploadRequest,
         WorkspaceFileUpload,
     )
@@ -390,6 +391,7 @@ def workspace_upload(
                 content_type=content_type,
                 encoding=WorkspaceFileEncoding.BASE64,
                 kind=WorkspaceFileKind.FILE,
+                mode=WorkspaceFileMode.from_posix_mode(resolved_source.stat().st_mode),
             )
         )
 

{synth_ai-0.20.2.dev643 → synth_ai-0.21.0.dev647}/synth_ai/mcp/research/README.md

@@ -49,8 +49,10 @@ becoming callable without a scope.
 
 `synth-ai-index-mcp` is the Index-only stdio entrypoint. It requires an explicit
 `SYNTH_BACKEND_URL`, advertises no unrelated Research tools, and defaults to
-read-only. Without `SYNTH_API_KEY` it advertises public browse tools only;
-authenticated search and durable-search lifecycle tools require the key.
+read-only. Without `SYNTH_API_KEY` it advertises public browse tools and the
+free public `index_search` (Index Search v0.2; price, limits and privacy
+terms are read from backend capabilities at call time, never hardcoded);
+`index_private_search` and the durable-search lifecycle tools require the key.
 `SYNTH_INDEX_MCP_WRITE_ENABLED=true` separately enables Contribution draft,
 upload, and submission tools. Tool discovery performs no backend request.
 

{synth_ai-0.20.2.dev643 → synth_ai-0.21.0.dev647}/synth_ai/mcp/research/server.py

@@ -504,7 +504,8 @@ class ResearchMcpServer:
                     tool
                     for tool in build_index_tools(
                         self._index_client_factory,
-                        include_search=self._default_api_key is not None,
+                        # The public search route (v0.2) is free and needs no key.
+                        include_search=True,
                         # /index/answer is not in the public launch.
                         include_answer=False,
                         include_lifecycle=self._default_api_key is not None,
@@ -2996,7 +2997,7 @@ def _stdio_server(*, index_only: bool = False) -> ResearchMcpServer:
 _INDEX_ENVIRONMENT_HELP = """\
 environment:
   SYNTH_BACKEND_URL              backend base URL (required when Index tools are enabled)
-  SYNTH_API_KEY                  API key; enables authenticated Search and answer tools
+  SYNTH_API_KEY                  API key; enables private/durable Search tools (public search needs none)
   SYNTH_INDEX_MCP_WRITE_ENABLED  true|false; Contribution write tools (needs SYNTH_API_KEY)
 """
 

{synth_ai-0.20.2.dev643 → synth_ai-0.21.0.dev647}/synth_ai/mcp/research/tools/index.py

@@ -21,16 +21,36 @@ from synth_ai.mcp.research.registry import (
 )
 from synth_ai.mcp.research.tools.local_files import SelectedFileReader
 from synth_ai.sdk.index.answer import AnswerSpec
-from synth_ai.sdk.index.client import STATUS_POLL_TIMEOUT_SECONDS, IndexAPI
+from synth_ai.sdk.index.catalog import PublicSearchCapability
+from synth_ai.sdk.index.client import STATUS_POLL_TIMEOUT_SECONDS, IndexAPI, PublicIndexAPI
 from synth_ai.sdk.index.contracts import ContributionReference, Identifier, IndexContract
 from synth_ai.sdk.index.contributions import ContributionDraft, ContributionUploadSpec
-from synth_ai.sdk.index.search import ContentsSpec, SearchSpec
+from synth_ai.sdk.index.public_search import (
+    DEFAULT_PUBLIC_SEARCH_WAIT_SECONDS,
+    PublicSearchDisabledError,
+    PublicSearchHandle,
+    PublicSearchResult,
+    public_search_copy,
+)
+from synth_ai.sdk.index.search import (
+    ContentsSpec,
+    SearchBillingConstraints,
+    SearchMode,
+    SearchResult,
+    SearchSpec,
+)
 from synth_ai.sdk.index.submission import ContributionSubmitSpec
+from synth_ai.sdk.index.wallet_search import (
+    AccessFundingCache,
+    WalletSearchGrant,
+    wallet_search_grant,
+)
 
-IndexClientFactory = Callable[[], AbstractContextManager[IndexAPI]]
+IndexClientFactory = Callable[[], AbstractContextManager[IndexAPI | PublicIndexAPI]]
 
 INDEX_READ_TOOL_NAMES: tuple[str, ...] = (
     "index_search",
+    "index_private_search",
     "index_search_create",
     "index_search_get",
     "index_search_result",
@@ -60,12 +80,31 @@ _KEY = Field(min_length=1, max_length=128, pattern=r"^[a-zA-Z0-9_.-]+$")
 
 
 class IndexSearchRequest(IndexContract):
+    """Public (credential-optional) Index Search v0.2; price and limits come from capabilities."""
+
+    query: Annotated[str, Field(min_length=1, max_length=8192)]
+    mode: SearchMode = Field(
+        default=SearchMode.FAST,
+        description="fast answers synchronously; deep is admitted and polled to completion.",
+    )
+    max_results: Annotated[StrictInt, Field(ge=1, le=10)] | None = None
+    idempotency_key: str | None = Field(
+        default=None,
+        min_length=1,
+        max_length=128,
+        pattern=r"^[a-zA-Z0-9_.-]+$",
+        description="Optional stable key to replay the same intent after an uncertain response.",
+    )
+
+
+class IndexPrivateSearchRequest(IndexContract):
     search: SearchSpec = Field(
         description=(
-            "Search intent and caller-owned billing bound. Current FAST public and private "
-            "searches cost 5 cents; wallet funding needs billing.allow_wallet=true and "
-            "billing.max_charge_cents>=5. DEEP needs a mode grant and a ceiling of "
-            "at least 10 cents. Never infer funding consent from the query."
+            "Authenticated, funded search intent (private scope, wallet). The price per "
+            "search comes from capabilities.private_search.price_cents_per_search; wallet "
+            "funding needs billing.allow_wallet=true and a billing.max_charge_cents ceiling "
+            "at or above it. DEEP needs a mode grant. Never infer funding consent from the "
+            "query."
         )
     )
     idempotency_key: str = _KEY
@@ -123,29 +162,156 @@ def read_selected_files(root: str, files: Mapping[str, str]) -> dict[str, bytes]
     return content
 
 
+_PUBLIC_SEARCH_DESCRIPTION = (
+    "Search reviewed Synth Index Contributions (Index Search v0.2). Without an API key "
+    "this is the free public search; mode is fast (synchronous) or deep (admitted, then "
+    "polled to completion). Price, rate limits, retention and privacy terms are published "
+    "by the backend's capabilities and returned under `terms` with every result; this tool "
+    "never assumes a price. With an API key a call is a PAID search charged to your "
+    "organization's wallet, and it runs only if your organization has turned on wallet "
+    "payments for that mode; the result reports the `charge`. Otherwise it is refused "
+    "with index_wallet_consent_required, the steps to enable it, and no charge. A rate-limit error carries retry_after_seconds and the limit scope; "
+    "a 503 means the search failed closed and nothing was charged. `response` cites "
+    "contribution ids inline as [<contribution_id>]; `citations` lists the exact revisions "
+    "(contribution_id, revision_id) in first-appearance order; preserve them verbatim."
+)
+
+
+def public_search_tool_description(capability: PublicSearchCapability | None) -> str:
+    """Tool text built from the backend's capabilities; nothing priced by hand."""
+    if capability is None:
+        return _PUBLIC_SEARCH_DESCRIPTION
+    copy = public_search_copy(capability)
+    return " ".join((*copy.lines, _PUBLIC_SEARCH_DESCRIPTION))
+
+
+def _public_search_payload(result: PublicSearchResult) -> JSONDict:
+    return {
+        "search_id": result.search_id,
+        "mode": result.mode.value,
+        "status": result.status,
+        "response": result.response,
+        "partial_reason": result.partial_reason,
+        "citations": [
+            {"contribution_id": item.contribution_id, "revision_id": item.revision_id}
+            for item in result.citations
+        ],
+        "customer_charge_cents": result.customer_charge_cents,
+        "monitor_release_id": result.monitor_release_id,
+    }
+
+
+def _paid_search_payload(result: SearchResult, grant: WalletSearchGrant) -> JSONDict:
+    usage = result.usage
+    return {
+        "search_id": result.search_id,
+        "mode": result.effective_mode.value,
+        "status": result.status,
+        "response": result.response,
+        "partial_reason": (None if result.partial_reason is None else result.partial_reason.value),
+        "citations": [
+            {"contribution_id": item.contribution_id, "revision_id": item.revision_id}
+            for item in result.citations
+        ],
+        "paid": True,
+        "customer_charge_cents": usage.amount_cents,
+        "charge": {
+            "amount_cents": usage.amount_cents,
+            "wallet_debit_cents": usage.wallet_debit_cents,
+            "funding_source": usage.funding_source,
+            "receipt_id": usage.receipt_id,
+            "max_charge_cents": grant.max_charge_cents,
+        },
+    }
+
+
 def build_index_tools(
     client_factory: IndexClientFactory,
     *,
     include_search: bool = True,
     include_answer: bool = False,
     include_lifecycle: bool = True,
+    public_search_capability: PublicSearchCapability | None = None,
 ) -> list[ToolDefinition]:
     """Build Index tools without discovering credentials or widening scope.
 
-    Search requires an explicit stable key because private or deep searches may
-    consume bounded service resources. Backend authorization, execution and usage
+    ``index_search`` without a key is the free public route. With a key it is
+    the paid search, run only when the org has consented to wallet funding
+    for the mode (a cached access-funding read), with an explicit per-call
+    ceiling; otherwise it raises ``WalletConsentRequiredError`` before any paid
+    request is sent (owner decision 2026-09-28). Private and
+    lifecycle search require an explicit stable key because they may consume
+    bounded, funded service resources. Backend authorization, execution and usage
     remain authoritative; no local search or model fallback is installed.
+    ``public_search_capability`` (when the caller already holds it) puts the
+    backend's price/limits/privacy copy into the tool description; discovery
+    itself never makes a request.
     """
 
+    funding_cache = AccessFundingCache()
+
+    def keyed_search(client: IndexAPI, request: IndexSearchRequest) -> JSONDict:
+        account = funding_cache.get(client.account.access_funding)
+        grant = wallet_search_grant(account, request.mode)
+        try:
+            result = client.search(
+                query=request.query,
+                mode=request.mode,
+                max_results=request.max_results,
+                billing=SearchBillingConstraints(
+                    allow_wallet=True, max_charge_cents=grant.max_charge_cents
+                ),
+                idempotency_key=request.idempotency_key,
+            )
+        except Exception:
+            # Consent or caps may have changed server-side: read them again next call.
+            funding_cache.invalidate()
+            raise
+        return _paid_search_payload(result, grant)
+
     def search(arguments: JSONDict) -> JSONDict:
         request = IndexSearchRequest.model_validate(arguments)
         with client_factory() as client:
+            if isinstance(client, IndexAPI):
+                # The public route is anonymous-only (backend 409). A keyed call is
+                # paid, and only runs when the org has opted in to wallet funding.
+                return keyed_search(client, request)
+            capability = client.public_search_capability()
+            if capability is None or not capability.enabled:
+                raise PublicSearchDisabledError(
+                    "Public Index search is not enabled on this backend", status=404
+                )
+            if request.mode not in capability.modes:
+                raise PublicSearchDisabledError(
+                    f"Public Index search does not offer mode {request.mode.value!r}",
+                    status=404,
+                )
+            outcome = client.public_search(
+                request.query,
+                mode=request.mode,
+                max_results=request.max_results,
+                idempotency_key=request.idempotency_key,
+                wait=True,
+                timeout_s=DEFAULT_PUBLIC_SEARCH_WAIT_SECONDS,
+            )
+        if isinstance(outcome, PublicSearchHandle):  # pragma: no cover - wait=True
+            raise RuntimeError("public search returned a handle while waiting")
+        return {
+            **_public_search_payload(outcome),
+            "terms": public_search_copy(capability).as_dict(),
+        }
+
+    def private_search(arguments: JSONDict) -> JSONDict:
+        request = IndexPrivateSearchRequest.model_validate(arguments)
+        with client_factory() as client:
+            if not isinstance(client, IndexAPI):
+                raise ValueError("index_private_search requires an API key")
             return client.search(
                 request.search, idempotency_key=request.idempotency_key
             ).model_dump(mode="json")
 
     def search_create(arguments: JSONDict) -> JSONDict:
-        request = IndexSearchRequest.model_validate(arguments)
+        request = IndexPrivateSearchRequest.model_validate(arguments)
         with client_factory() as client:
             return client.searches.create(
                 request.search, idempotency_key=request.idempotency_key
@@ -235,15 +401,22 @@ def build_index_tools(
     tools = [
         ToolDefinition(
             name="index_search",
-            description="Search reviewed Synth Index Contributions with an authenticated funding identity. Current FAST public and private searches cost 5 cents; wallet funding requires search.billing.allow_wallet=true and max_charge_cents>=5. Do not infer consent. Reuse the same idempotency key for uncertain retries (never a new key for the same intent); if an error carries search_id, reconnect with index_search_get. Preserve exact revision citations.",
+            description=public_search_tool_description(public_search_capability),
             input_schema=IndexSearchRequest.model_json_schema(),
             handler=search,
             required_scopes=read,
         ),
+        ToolDefinition(
+            name="index_private_search",
+            description="Search with an authenticated funding identity (private scope or wallet-funded). The per-search price is capabilities.private_search.price_cents_per_search; wallet funding requires search.billing.allow_wallet=true and a max_charge_cents ceiling at or above it. Do not infer consent. Reuse the same idempotency key for uncertain retries (never a new key for the same intent); if an error carries search_id, reconnect with index_search_get. Preserve exact revision citations.",
+            input_schema=IndexPrivateSearchRequest.model_json_schema(),
+            handler=private_search,
+            required_scopes=read,
+        ),
         ToolDefinition(
             name="index_search_create",
-            description="Create one durable FAST or DEEP Search. Current FAST public/private wallet searches need explicit consent and a ceiling of at least 5 cents; DEEP needs a mode grant and at least 10 cents. Return its Search ID and state immediately. Always send a stable idempotency key: after an uncertain response or a transient 503, retry with the SAME key (the SDK retries automatically); if an error carries search_id, the Search was admitted, so read it with index_search_get instead of creating another.",
-            input_schema=IndexSearchRequest.model_json_schema(),
+            description="Create one durable FAST or DEEP authenticated Search. Wallet-funded searches need explicit consent and a max_charge_cents ceiling at or above the price published in capabilities; DEEP needs a mode grant. Return its Search ID and state immediately. Always send a stable idempotency key: after an uncertain response or a transient 503, retry with the SAME key (the SDK retries automatically); if an error carries search_id, the Search was admitted, so read it with index_search_get instead of creating another.",
+            input_schema=IndexPrivateSearchRequest.model_json_schema(),
             handler=search_create,
             required_scopes=read,
         ),
@@ -326,6 +499,7 @@ def build_index_tools(
         ),
     ]
     lifecycle_names = {
+        "index_private_search",
         "index_search_create",
         "index_search_get",
         "index_search_result",

{synth_ai-0.20.2.dev643 → synth_ai-0.21.0.dev647}/synth_ai/mcp/research/tools/workspace_inputs.py

@@ -18,6 +18,7 @@ from synth_ai.sdk.research.contracts.workspaces import (
     WORKSPACE_BATCH_UPLOAD_FILE_LIMIT,
     WorkspaceFileEncoding,
     WorkspaceFileKind,
+    WorkspaceFileMode,
     WorkspaceFilesBatchUploadRequest,
     WorkspaceFileUpload,
     WorkspaceMetadata,
@@ -26,7 +27,9 @@ from synth_ai.sdk.research.contracts.workspaces import (
 
 CoreClientFactory = Callable[[JSONDict], ResearchClient]
 
-_FILE_FIELDS = frozenset({"path", "content", "content_type", "encoding", "kind", "metadata"})
+_FILE_FIELDS = frozenset(
+    {"path", "content", "content_type", "encoding", "kind", "mode", "metadata"}
+)
 
 
 def _file_upload(value: object, *, index: int) -> WorkspaceFileUpload:
@@ -52,6 +55,9 @@ def _file_upload(value: object, *, index: int) -> WorkspaceFileUpload:
     kind = value.get("kind")
     if kind is not None and not isinstance(kind, str):
         raise ValueError(f"files[{index}].kind must be a string")
+    mode = value.get("mode")
+    if mode is not None and not isinstance(mode, str):
+        raise ValueError(f"files[{index}].mode must be a string")
     metadata = value.get("metadata", {})
     if not isinstance(metadata, dict):
         raise ValueError(f"files[{index}].metadata must be an object")
@@ -61,6 +67,7 @@ def _file_upload(value: object, *, index: int) -> WorkspaceFileUpload:
         content_type=content_type,
         encoding=WorkspaceFileEncoding(encoding) if encoding is not None else None,
         kind=WorkspaceFileKind(kind) if kind is not None else None,
+        mode=WorkspaceFileMode(mode) if mode is not None else None,
         metadata=WorkspaceMetadata(metadata),
     )
 
@@ -194,6 +201,11 @@ def build_workspace_input_tools(
                                     "type": "string",
                                     "enum": [item.value for item in WorkspaceFileKind],
                                 },
+                                "mode": {
+                                    "type": "string",
+                                    "enum": [item.value for item in WorkspaceFileMode],
+                                    "description": "Git blob mode; 100755 commits the file executable.",
+                                },
                                 "metadata": {"type": "object"},
                             },
                             "required": ["path", "content"],

{synth_ai-0.20.2.dev643 → synth_ai-0.21.0.dev647}/synth_ai/sdk/index/AGENT_SETUP_PROMPT.md

@@ -20,19 +20,23 @@ product UI or to run a paid search during setup.
 > without my explicit authorization for that operation. If the backend URL or
 > authorized key source is missing, report exactly what is missing and stop.
 >
-> Verify that the server starts and advertises `index_search` and
-> `index_search_create` with the key. Without a key it may advertise public
-> browse tools, but it must not advertise search or durable-search lifecycle
-> tools. Tool discovery must not execute a search or incur a charge.
+> Verify that the server starts and advertises `index_search` (the public
+> route, available with or without a key) and, with the key, `index_private_search`
+> and `index_search_create`. Without a key it must not advertise private or
+> durable-search lifecycle tools. Tool discovery must not execute a search or
+> incur a charge.
 >
-> For a later search I explicitly request, first state the aggregate maximum
-> charge and use a fresh idempotency key. Current public- and private-scope FAST
-> searches are both priced at 5 cents. Wallet funding requires
-> `search.billing.allow_wallet=true` and `max_charge_cents` of at least 5; do
-> not infer my wallet consent from a query. DEEP also needs a mode grant and a
-> ceiling of at least 10 cents. If a response is uncertain, retry the same
-> logical request with the **same** idempotency key, not a new charge attempt.
-> Preserve returned Contribution and revision IDs when reporting evidence.
+> Public `index_search` (fast or deep) is priced, rate-limited and governed by the
+> privacy terms the backend publishes in capabilities; the tool returns them under
+> `terms` with every result. Never quote a price you did not read from there.
+> For a private or wallet-funded search I explicitly request, first state the
+> aggregate maximum charge and use a fresh idempotency key. Wallet funding
+> requires `search.billing.allow_wallet=true` and a `max_charge_cents` ceiling
+> at or above `capabilities.private_search.price_cents_per_search`; do not infer
+> my wallet consent from a query. DEEP also needs a mode grant. If a response is
+> uncertain, retry the same logical request with the **same** idempotency key,
+> not a new charge attempt. Preserve returned Contribution and revision IDs when
+> reporting evidence.
 > Do not enable Contribution writes unless I separately ask for them.
 >
 > Report the package version, backend environment name (not a secret), MCP