synth-ai 0.20.0.dev628__tar.gz → 0.20.0.dev629__tar.gz

{synth_ai-0.20.0.dev628/synth_ai.egg-info → synth_ai-0.20.0.dev629}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synth-ai
-Version: 0.20.0.dev628
+Version: 0.20.0.dev629
 Summary: Python SDK and CLI for Synth Managed Research and Research Factory
 Author-email: Synth AI <josh@usesynth.ai>
 License-Expression: MIT

{synth_ai-0.20.0.dev628 → synth_ai-0.20.0.dev629}/openapi/index-v1.json

@@ -650,7 +650,7 @@
         "properties": {
           "concurrency_limit": {
             "default": 1,
-            "maximum": 32.0,
+            "maximum": 50.0,
             "minimum": 1.0,
             "title": "Concurrency Limit",
             "type": "integer"
@@ -3320,80 +3320,6 @@
         "title": "PromoCreditSummary",
         "type": "object"
       },
-      "PublicSearchResult": {
-        "additionalProperties": false,
-        "description": "Anonymous public search: text citing contribution IDs, like every Index search.\n\nSame response rule as the authenticated ``SearchResult`` (inline\n``[<contribution_id>]`` markers equal ``citations`` in first-appearance\norder); no ranked hits, excerpts, titles or URLs.",
-        "properties": {
-          "amount_cents": {
-            "const": 0,
-            "default": 0,
-            "title": "Amount Cents",
-            "type": "integer"
-          },
-          "citations": {
-            "items": {
-              "$ref": "#/components/schemas/ContributionReference"
-            },
-            "maxItems": 10,
-            "title": "Citations",
-            "type": "array"
-          },
-          "corpus_generation": {
-            "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$",
-            "title": "Corpus Generation",
-            "type": "string"
-          },
-          "mode": {
-            "const": "fast",
-            "default": "fast",
-            "title": "Mode",
-            "type": "string"
-          },
-          "parser_version": {
-            "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$",
-            "title": "Parser Version",
-            "type": "string"
-          },
-          "ranker_version": {
-            "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$",
-            "title": "Ranker Version",
-            "type": "string"
-          },
-          "request_id": {
-            "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$",
-            "title": "Request Id",
-            "type": "string"
-          },
-          "response": {
-            "maxLength": 16384,
-            "minLength": 1,
-            "title": "Response",
-            "type": "string"
-          },
-          "status": {
-            "const": "completed",
-            "default": "completed",
-            "title": "Status",
-            "type": "string"
-          },
-          "taxonomy_version": {
-            "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$",
-            "title": "Taxonomy Version",
-            "type": "string"
-          }
-        },
-        "required": [
-          "request_id",
-          "corpus_generation",
-          "ranker_version",
-          "parser_version",
-          "taxonomy_version",
-          "response",
-          "citations"
-        ],
-        "title": "PublicSearchResult",
-        "type": "object"
-      },
       "PublicUsage": {
         "additionalProperties": false,
         "properties": {
@@ -4805,7 +4731,7 @@
       },
       "SearchExecutionVersions": {
         "additionalProperties": false,
-        "description": "Exact implementation identities used by one result.",
+        "description": "Exact implementation identities used by one result.\n\nAn identity the execution did not use is omitted, never ``null``.",
         "properties": {
           "agent_version": {
             "anyOf": [
@@ -5137,6 +5063,7 @@
           "complete",
           "insufficient_evidence",
           "usable_partial",
+          "infrastructure_stopped",
           "no_deliverable",
           "infrastructure_failure",
           "cancelled",
@@ -5320,7 +5247,7 @@
                 "type": "null"
               }
             ],
-            "default": "synth.index.fast.v1",
+            "default": "synth.index.fast.v2",
             "title": "Price Version"
           },
           "read_calls": {
@@ -8906,47 +8833,6 @@
         ]
       }
     },
-    "/api/v1/index/public/search": {
-      "post": {
-        "operationId": "index.public.search",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/SearchSpec-Input"
-              }
-            }
-          },
-          "required": true
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/PublicSearchResult"
-                }
-              }
-            },
-            "description": "Successful Response"
-          },
-          "422": {
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/HTTPValidationError"
-                }
-              }
-            },
-            "description": "Validation Error"
-          }
-        },
-        "summary": "Search",
-        "tags": [
-          "index-public"
-        ]
-      }
-    },
     "/api/v1/index/public/tags": {
       "get": {
         "operationId": "index.public.tags.list",

{synth_ai-0.20.0.dev628 → synth_ai-0.20.0.dev629}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "synth-ai"
-version = "0.20.0.dev628"
+version = "0.20.0.dev629"
 description = "Python SDK and CLI for Synth Managed Research and Research Factory"
 authors = [{name = "Synth AI", email = "josh@usesynth.ai"}]
 license = "MIT"
@@ -18,6 +18,7 @@ dependencies = [
 [project.scripts]
 synth-ai = "synth_ai.cli:cli"
 synth-ai-research-mcp = "synth_ai.mcp.research.server:main"
+synth-ai-index-mcp = "synth_ai.mcp.research.server:main_index"
 
 [project.optional-dependencies]
 pools = [

{synth_ai-0.20.0.dev628 → synth_ai-0.20.0.dev629}/setup.py

@@ -5,13 +5,12 @@ contract bytes as the reviewed source. Keep openapi/ as the single source and
 copy only the three public contract snapshots into the wheel, never other JSON.
 """
 
-from pathlib import Path
 import shutil
+from pathlib import Path
 
 from setuptools import setup
 from setuptools.command.build_py import build_py
 
-
 SCHEMAS = ("index-v1.json", "research-v1.json", "messaging-v1.json")
 
 

{synth_ai-0.20.0.dev628 → synth_ai-0.20.0.dev629}/synth_ai/cli/index.py

@@ -19,10 +19,10 @@ def index() -> None:
 @click.option("--max-results", type=click.IntRange(1, 10), default=5, show_default=True)
 @click.option(
     "--deadline-seconds",
-    type=click.IntRange(1, 90),
-    default=90,
+    type=click.IntRange(1, 300),
+    default=180,
     show_default=True,
-    help="Deep execution ceiling; ignored for fast only by omitting it from the request.",
+    help="Durable Deep execution ceiling; omitted from fast requests.",
 )
 @click.option(
     "--private-collection",
@@ -31,6 +31,10 @@ def index() -> None:
     help="Search only these authorized private collection IDs.",
 )
 @click.option("--idempotency-key", help="Stable retry identity for this logical search.")
+@click.option("--allow-wallet", is_flag=True, help="Explicitly allow wallet funding.")
+@click.option(
+    "--max-charge-cents", type=click.IntRange(0, 1_000_000), help="Maximum charge in cents."
+)
 @click.option("--backend-url", envvar="SYNTH_BACKEND_URL", help="Synth backend base URL.")
 @click.option("--api-key", envvar="SYNTH_API_KEY", help="Authorized Synth API key.")
 def search(
@@ -40,6 +44,8 @@ def search(
     deadline_seconds: int,
     private_collections: tuple[str, ...],
     idempotency_key: str | None,
+    allow_wallet: bool,
+    max_charge_cents: int | None,
     backend_url: str | None,
     api_key: str | None,
 ) -> None:
@@ -49,6 +55,7 @@ def search(
     from synth_ai import SynthClient
     from synth_ai.core.errors import SynthError
     from synth_ai.sdk.index.search import (
+        SearchBillingConstraints,
         SearchExecutionCancelledError,
         SearchExecutionFailedError,
         SearchExecutionLimits,
@@ -78,6 +85,9 @@ def search(
                 scope=scope,
                 max_results=max_results,
                 limits=limits,
+                billing=SearchBillingConstraints(
+                    allow_wallet=allow_wallet, max_charge_cents=max_charge_cents
+                ),
                 idempotency_key=idempotency_key,
             )
     except (
@@ -125,6 +135,12 @@ def search(
     required=True,
     help="Stable retry identity for retrieval, admission and synthesis.",
 )
+@click.option("--allow-wallet", is_flag=True, help="Explicitly allow wallet funding for retrieval.")
+@click.option(
+    "--max-charge-cents",
+    type=click.IntRange(0, 1_000_000),
+    help="Maximum retrieval charge in cents.",
+)
 @click.option("--backend-url", envvar="SYNTH_BACKEND_URL", help="Synth backend base URL.")
 @click.option("--api-key", envvar="SYNTH_API_KEY", help="Authorized Synth API key.")
 def answer(
@@ -136,6 +152,8 @@ def answer(
     deadline_seconds: int,
     private_collections: tuple[str, ...],
     idempotency_key: str,
+    allow_wallet: bool,
+    max_charge_cents: int | None,
     backend_url: str | None,
     api_key: str | None,
 ) -> None:
@@ -145,6 +163,7 @@ def answer(
     from synth_ai import SynthClient
     from synth_ai.core.errors import SynthError
     from synth_ai.sdk.index.search import (
+        SearchBillingConstraints,
         SearchExecutionLimits,
         SearchMode,
         SearchScope,
@@ -173,6 +192,9 @@ def answer(
                 limits=limits,
                 max_answer_tokens=max_answer_tokens,
                 max_answer_cost_usd_micros=max_answer_cost_usd_micros,
+                billing=SearchBillingConstraints(
+                    allow_wallet=allow_wallet, max_charge_cents=max_charge_cents
+                ),
                 idempotency_key=idempotency_key,
             )
     except (ValueError, SynthError, HTTPError) as error:
@@ -192,11 +214,15 @@ def searches() -> None:
 @click.argument("query")
 @click.option("--mode", type=click.Choice(("fast", "deep")), default="deep", show_default=True)
 @click.option("--max-results", type=click.IntRange(1, 10), default=5, show_default=True)
-@click.option("--deadline-seconds", type=click.IntRange(1, 90), default=90, show_default=True)
+@click.option("--deadline-seconds", type=click.IntRange(1, 300), default=180, show_default=True)
 @click.option("--private-collection", "private_collections", multiple=True)
 @click.option(
     "--idempotency-key", required=True, help="Reuse this key after an uncertain response."
 )
+@click.option("--allow-wallet", is_flag=True, help="Explicitly allow wallet funding.")
+@click.option(
+    "--max-charge-cents", type=click.IntRange(0, 1_000_000), help="Maximum charge in cents."
+)
 @click.option("--backend-url", envvar="SYNTH_BACKEND_URL")
 @click.option("--api-key", envvar="SYNTH_API_KEY")
 def searches_create(
@@ -206,6 +232,8 @@ def searches_create(
     deadline_seconds: int,
     private_collections: tuple[str, ...],
     idempotency_key: str,
+    allow_wallet: bool,
+    max_charge_cents: int | None,
     backend_url: str | None,
     api_key: str | None,
 ) -> None:
@@ -215,6 +243,7 @@ def searches_create(
     from synth_ai import SynthClient
     from synth_ai.core.errors import SynthError
     from synth_ai.sdk.index.search import (
+        SearchBillingConstraints,
         SearchContent,
         SearchExecutionLimits,
         SearchMode,
@@ -240,6 +269,9 @@ def searches_create(
                 if selected_mode is SearchMode.DEEP
                 else None
             ),
+            billing=SearchBillingConstraints(
+                allow_wallet=allow_wallet, max_charge_cents=max_charge_cents
+            ),
         )
         with SynthClient(api_key=api_key, base_url=backend_url) as client:
             snapshot = client.index.searches.create(spec, idempotency_key=idempotency_key).snapshot
@@ -376,9 +408,9 @@ def submit(
     from synth_ai import SynthClient
     from synth_ai.core.errors import SynthError
     from synth_ai.sdk.index.research_intake import (
-        IntakeLocked,
+        IntakeLockedError,
         IntakeStateError,
-        TerminalRevision,
+        TerminalRevisionError,
         submit_conversion,
     )
 
@@ -397,9 +429,9 @@ def submit(
         TypeError,
         SynthError,
         HTTPError,
-        IntakeLocked,
+        IntakeLockedError,
         IntakeStateError,
-        TerminalRevision,
+        TerminalRevisionError,
     ) as error:
         raise click.ClickException(str(error)) from error
     click.echo(json.dumps(result, indent=2, sort_keys=True))

{synth_ai-0.20.0.dev628 → synth_ai-0.20.0.dev629}/synth_ai/mcp/research/README.md

@@ -47,6 +47,13 @@ becoming callable without a scope.
 
 ## What the entrypoint advertises
 
+`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.
+`SYNTH_INDEX_MCP_WRITE_ENABLED=true` separately enables Contribution draft,
+upload, and submission tools. Tool discovery performs no backend request.
+
 `synth-ai-research-mcp` advertises the stable subset (64 of 254 tools). The rest
 are built but hidden, and because `call_tool` resolves against the advertised
 set they are also uncallable. Set `SYNTH_RESEARCH_MCP_ADVANCED_TOOLS=1` to

{synth_ai-0.20.0.dev628 → synth_ai-0.20.0.dev629}/synth_ai/mcp/research/server.py

@@ -413,15 +413,19 @@ class ResearchMcpServer:
         include_advanced_tools: bool = False,
         index_client_factory: IndexClientFactory | None = None,
         index_write_enabled: bool = True,
+        index_only: bool = False,
     ) -> None:
-        self._default_api_key = api_key
+        self._default_api_key = api_key or None
         self._default_backend_base = backend_base
         self._include_advanced_tools = include_advanced_tools
         self._index_client_factory = index_client_factory
         self._index_write_enabled = index_write_enabled
+        self._index_only = index_only
         self._tools = build_tool_registry(self._build_tools())
 
     def _advertised_tools(self) -> dict[str, ToolDefinition]:
+        if self._index_only:
+            return {name: tool for name, tool in self._tools.items() if name in INDEX_TOOL_NAMES}
         if self._include_advanced_tools:
             return self._tools
         return {
@@ -484,6 +488,7 @@ class ResearchMcpServer:
                     tool
                     for tool in build_index_tools(
                         self._index_client_factory,
+                        include_search=self._default_api_key is not None,
                         include_answer=self._default_api_key is not None,
                         include_lifecycle=self._default_api_key is not None,
                     )
@@ -2799,7 +2804,10 @@ class ResearchMcpServer:
                     "id": request_id,
                     "result": {
                         "protocolVersion": DEFAULT_PROTOCOL_VERSION,
-                        "serverInfo": {"name": SERVER_NAME, "version": __version__},
+                        "serverInfo": {
+                            "name": "synth-index" if self._index_only else SERVER_NAME,
+                            "version": __version__,
+                        },
                         "capabilities": {"tools": {}},
                     },
                 }
@@ -2887,7 +2895,7 @@ def _explicit_index_flag(name: str) -> bool:
     return value == "true"
 
 
-def _stdio_server() -> ResearchMcpServer:
+def _stdio_server(*, index_only: bool = False) -> ResearchMcpServer:
     """Capture explicit Index process config; construct clients only on invocation.
 
     No credential discovery, home files, or network access during MCP discovery.
@@ -2895,7 +2903,7 @@ def _stdio_server() -> ResearchMcpServer:
     """
     from contextlib import contextmanager
 
-    enabled = _explicit_index_flag("SYNTH_INDEX_MCP_ENABLED")
+    enabled = index_only or _explicit_index_flag("SYNTH_INDEX_MCP_ENABLED")
     writes = _explicit_index_flag("SYNTH_INDEX_MCP_WRITE_ENABLED")
     if writes and not enabled:
         raise ValueError("Index MCP writes require SYNTH_INDEX_MCP_ENABLED=true")
@@ -2903,7 +2911,7 @@ def _stdio_server() -> ResearchMcpServer:
     api_key = None
     backend_base = None
     if enabled:
-        api_key = os.environ.get("SYNTH_API_KEY", "").strip()
+        api_key = os.environ.get("SYNTH_API_KEY", "").strip() or None
         backend_base = os.environ.get("SYNTH_BACKEND_URL", "").strip()
         if not backend_base:
             raise ValueError("Index MCP requires explicit SYNTH_BACKEND_URL")
@@ -2948,6 +2956,7 @@ def _stdio_server() -> ResearchMcpServer:
         include_advanced_tools=_advanced_tools_requested(),
         index_client_factory=factory,
         index_write_enabled=writes,
+        index_only=index_only,
     )
 
 
@@ -2956,6 +2965,11 @@ def main() -> None:
     _stdio_server().serve_stdio()
 
 
+def main_index() -> None:
+    """Index-only stdio MCP entrypoint; no unrelated Research tools."""
+    _stdio_server(index_only=True).serve_stdio()
+
+
 __all__ = [
     "ADVANCED_TOOLS_ENV",
     "DEFAULT_PROTOCOL_VERSION",
@@ -2964,4 +2978,5 @@ __all__ = [
     "SUPPORTED_PROTOCOL_VERSIONS",
     "_read_message",
     "main",
+    "main_index",
 ]

{synth_ai-0.20.0.dev628 → synth_ai-0.20.0.dev629}/synth_ai/mcp/research/tools/index.py

@@ -57,7 +57,14 @@ _KEY = Field(min_length=1, max_length=128, pattern=r"^[a-zA-Z0-9_.-]+$")
 
 
 class IndexSearchRequest(IndexContract):
-    search: SearchSpec
+    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."
+        )
+    )
     idempotency_key: str = _KEY
 
 
@@ -116,6 +123,7 @@ def read_selected_files(root: str, files: Mapping[str, str]) -> dict[str, bytes]
 def build_index_tools(
     client_factory: IndexClientFactory,
     *,
+    include_search: bool = True,
     include_answer: bool = True,
     include_lifecycle: bool = True,
 ) -> list[ToolDefinition]:
@@ -219,14 +227,14 @@ def build_index_tools(
     tools = [
         ToolDefinition(
             name="index_search",
-            description="Search reviewed Synth Index research Contributions. Public callers can use fast mode; authenticated callers can use durable deep mode. Reuse the same idempotency key when retrying a logical search. Preserve exact revision citations.",
+            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 and preserve exact revision citations.",
             input_schema=IndexSearchRequest.model_json_schema(),
             handler=search,
             required_scopes=read,
         ),
         ToolDefinition(
             name="index_search_create",
-            description="Create one durable fast or deep Search. Return its Search ID and state immediately; reuse the idempotency key after uncertain responses.",
+            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; reuse the idempotency key after uncertain responses.",
             input_schema=IndexSearchRequest.model_json_schema(),
             handler=search_create,
             required_scopes=read,
@@ -319,6 +327,7 @@ def build_index_tools(
     return [
         tool
         for tool in tools
-        if (include_answer or tool.name != "index_answer")
+        if (include_search or tool.name != "index_search")
+        and (include_answer or tool.name != "index_answer")
         and (include_lifecycle or tool.name not in lifecycle_names)
     ]

synth_ai-0.20.0.dev629/synth_ai/sdk/index/AGENT_SETUP_PROMPT.md

@@ -0,0 +1,46 @@
+# Coding-agent setup prompt for Synth Index
+
+Copy the text below into a coding-agent task after you have chosen the Synth
+backend environment and an authorized way to supply its API key. This prompt
+configures an API/MCP integration; it does not ask the agent to build an Index
+product UI or to run a paid search during setup.
+
+> Set up Synth Index for this coding project through the `synth-ai` Python SDK
+> and its `synth-ai-index-mcp` stdio server. Index usage is API/MCP-only. Do
+> not add a search page, browser proxy, or customer-facing product workflow.
+>
+> First inspect the project's existing Python environment and coding-agent MCP
+> configuration. Use the supported `synth-ai` package and verify that the
+> `synth-ai-index-mcp` executable is available. Configure one MCP server with
+> `SYNTH_INDEX_MCP_WRITE_ENABLED=false` and an
+> explicit `SYNTH_BACKEND_URL` for the environment I named. Supply
+> `SYNTH_API_KEY` only through this project's already-authorized, non-committed
+> secret-injection mechanism. Never print, commit, paste into chat, or place the
+> key in tool arguments. Do not use macOS Keychain or another credential store
+> 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.
+>
+> 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.
+> Do not enable Contribution writes unless I separately ask for them.
+>
+> Report the package version, backend environment name (not a secret), MCP
+> server configuration with secret values redacted, advertised Index tool names,
+> and any blocker. Do not claim live search works unless a separately
+> authorized search actually completes and yields a receipt.
+
+The server entry point and environment flags are documented in
+[`README.md`](README.md). The typed billing object is
+`SearchBillingConstraints` in [`search.py`](search.py); the backend remains the
+authority for grants, balances, prices, and receipts.