SDKPython

Python

Syntic Code does not have a published Python package yet. Nothing is available on PyPI to install, and this page does not describe a Python API, because none has been released.

Until a package is published, a Python program drives Syntic Code by starting the syntic binary as a subprocess and reading its output. That interface is available today.

The syntic binary is the same program the interactive CLI runs. Install it as described in Install, and make sure it is on the PATH of the process that starts it.

Run one task

Start syntic with -p and --output-format json, then parse the one JSON object it prints:

import json
import subprocess
 
proc = subprocess.run(
    ["syntic", "-p", "list the exported functions in src/index.py", "--output-format", "json"],
    capture_output=True,
    text=True,
    check=False,
)
result = json.loads(proc.stdout)
if proc.returncode != 0 or result.get("is_error"):
    raise RuntimeError(result.get("result", proc.stderr))
print(result["result"])
print("estimated cost (USD):", result.get("total_cost_usd"))

Check both the exit status and is_error. A run that stops at a budget or turn limit reports its stop reason in the result.

Set limits and permissions for the run

Pass the same flags the command line takes. A program should decide these before it starts a run, because no one is there to answer a permission prompt.

args = [
    "syntic", "-p", "fix the failing unit tests",
    "--permission-mode", "acceptEdits",
    "--allowed-tools", "Bash(npm test:*)",
    "--max-budget-usd", "2",
    "--max-turns", "30",
    "--output-format", "json",
]

See Permissions for programs and Cost tracking for programs.

Stream the messages

For progress during a run, use --output-format stream-json --verbose. Read standard output line by line; each line is one JSON message, starting with an init record and ending with a result.

proc = subprocess.Popen(
    ["syntic", "-p", "review the open pull request diff",
     "--output-format", "stream-json", "--verbose"],
    stdout=subprocess.PIPE,
    text=True,
)
for line in proc.stdout:
    message = json.loads(line)
    print(message.get("type"))

Approve tool calls from code

Start the run with --input-format stream-json --output-format stream-json --verbose --permission-prompt-tool stdio. When a tool call needs approval, Syntic Code writes a control_request with subtype can_use_tool, the tool name and its input. Reply on standard input with a control_response that carries the same request_id and {"behavior": "allow"} or {"behavior": "deny", "message": "why"}. Any other answer is a denial. See User input.

What is not available yet

  • A published Python package with typed classes. Drive the syntic command as shown above.
  • A persistent-session preview package. Several turns in one process work today through streaming input; see TypeScript v2 preview.