tether-agents 0.3.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- tether/__init__.py +50 -0
- tether/_proto/__init__.py +0 -0
- tether/_proto/tether_pb2.py +62 -0
- tether/_proto/tether_pb2_grpc.py +370 -0
- tether/_run.py +381 -0
- tether_agents-0.3.0.dist-info/METADATA +113 -0
- tether_agents-0.3.0.dist-info/RECORD +8 -0
- tether_agents-0.3.0.dist-info/WHEEL +4 -0
tether/__init__.py
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
"""Python client for Tether.
|
|
2
|
+
|
|
3
|
+
Your agent keeps its own loop. It calls :meth:`Run.complete` where it called
|
|
4
|
+
its provider SDK and :meth:`Run.call_tool` where it ran a tool, and Tether
|
|
5
|
+
does the rest: policy, sandbox, budgets and the trace.
|
|
6
|
+
|
|
7
|
+
import tether
|
|
8
|
+
|
|
9
|
+
with tether.Run(policy="tether.toml") as run:
|
|
10
|
+
messages = [tether.user("Write hello.txt, then show me what is in it.")]
|
|
11
|
+
while True:
|
|
12
|
+
reply = run.complete(model="claude-opus-5-5", messages=messages)
|
|
13
|
+
messages.append(reply.message)
|
|
14
|
+
if not reply.tool_calls:
|
|
15
|
+
run.finish(reply.text)
|
|
16
|
+
break
|
|
17
|
+
results = [run.call_tool(call) for call in reply.tool_calls]
|
|
18
|
+
messages.append(tether.tool_results(results))
|
|
19
|
+
|
|
20
|
+
This module is a thin client for the daemon, ``tetherd``. Nothing here
|
|
21
|
+
decides anything: every call is one gRPC request.
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
from ._run import (
|
|
25
|
+
Event,
|
|
26
|
+
Halted,
|
|
27
|
+
Reply,
|
|
28
|
+
Run,
|
|
29
|
+
TetherError,
|
|
30
|
+
Tool,
|
|
31
|
+
ToolCall,
|
|
32
|
+
ToolResult,
|
|
33
|
+
system,
|
|
34
|
+
tool_results,
|
|
35
|
+
user,
|
|
36
|
+
)
|
|
37
|
+
|
|
38
|
+
__all__ = [
|
|
39
|
+
"Event",
|
|
40
|
+
"Halted",
|
|
41
|
+
"Reply",
|
|
42
|
+
"Run",
|
|
43
|
+
"TetherError",
|
|
44
|
+
"Tool",
|
|
45
|
+
"ToolCall",
|
|
46
|
+
"ToolResult",
|
|
47
|
+
"system",
|
|
48
|
+
"tool_results",
|
|
49
|
+
"user",
|
|
50
|
+
]
|
|
File without changes
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# -*- coding: utf-8 -*-
|
|
2
|
+
# Generated by the protocol buffer compiler. DO NOT EDIT!
|
|
3
|
+
# NO CHECKED-IN PROTOBUF GENCODE
|
|
4
|
+
# source: tether.proto
|
|
5
|
+
# Protobuf Python Version: 7.35.1
|
|
6
|
+
"""Generated protocol buffer code."""
|
|
7
|
+
from google.protobuf import descriptor as _descriptor
|
|
8
|
+
from google.protobuf import descriptor_pool as _descriptor_pool
|
|
9
|
+
from google.protobuf import runtime_version as _runtime_version
|
|
10
|
+
from google.protobuf import symbol_database as _symbol_database
|
|
11
|
+
from google.protobuf.internal import builder as _builder
|
|
12
|
+
_runtime_version.ValidateProtobufRuntimeVersion(
|
|
13
|
+
_runtime_version.Domain.PUBLIC,
|
|
14
|
+
7,
|
|
15
|
+
35,
|
|
16
|
+
1,
|
|
17
|
+
'',
|
|
18
|
+
'tether.proto'
|
|
19
|
+
)
|
|
20
|
+
# @@protoc_insertion_point(imports)
|
|
21
|
+
|
|
22
|
+
_sym_db = _symbol_database.Default()
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x0ctether.proto\x12\ttether.v1\"\x07\n\x05\x45mpty\"\x18\n\x06RunRef\x12\x0e\n\x06run_id\x18\x01 \x01(\t\"\x9d\x01\n\x10\x43reateRunRequest\x12\r\n\x05\x61gent\x18\x01 \x01(\t\x12\x13\n\x0bpolicy_path\x18\x02 \x01(\t\x12\x0f\n\x07sandbox\x18\x03 \x01(\t\x12\x11\n\tworkspace\x18\x04 \x01(\t\x12\x10\n\x08provider\x18\x05 \x01(\t\x12\x13\n\x0bscript_path\x18\x06 \x01(\t\x12\x0b\n\x03\x64ir\x18\x07 \x01(\t\x12\r\n\x05\x62\x65tas\x18\x08 \x03(\t\"M\n\x03Run\x12\x0e\n\x06run_id\x18\x01 \x01(\t\x12\x12\n\ntrace_path\x18\x02 \x01(\t\x12\"\n\x05tools\x18\x03 \x03(\x0b\x32\x13.tether.v1.ToolSpec\"X\n\x08ToolSpec\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x0e\n\x06server\x18\x02 \x01(\t\x12\x13\n\x0b\x64\x65scription\x18\x03 \x01(\t\x12\x19\n\x11input_schema_json\x18\x04 \x01(\t\"h\n\x0cModelRequest\x12\x0e\n\x06run_id\x18\x01 \x01(\t\x12\r\n\x05model\x18\x02 \x01(\t\x12\x15\n\rmessages_json\x18\x03 \x01(\t\x12\r\n\x05tools\x18\x04 \x03(\t\x12\x13\n\x0bparams_json\x18\x05 \x01(\t\"\xcd\x01\n\rModelResponse\x12\x14\n\x0cmessage_json\x18\x01 \x01(\t\x12\'\n\ntool_calls\x18\x02 \x03(\x0b\x32\x13.tether.v1.ToolCall\x12\x14\n\x0cinput_tokens\x18\x03 \x01(\x04\x12\x15\n\routput_tokens\x18\x04 \x01(\x04\x12\x13\n\x0bstop_reason\x18\x06 \x01(\t\x12\x19\n\x11\x63\x61\x63he_read_tokens\x18\x07 \x01(\x04\x12\x1a\n\x12\x63\x61\x63he_write_tokens\x18\x08 \x01(\x04J\x04\x08\x05\x10\x06\"<\n\x08ToolCall\x12\n\n\x02id\x18\x01 \x01(\t\x12\x0c\n\x04name\x18\x02 \x01(\t\x12\x16\n\x0e\x61rguments_json\x18\x03 \x01(\t\"D\n\x0fToolCallRequest\x12\x0e\n\x06run_id\x18\x01 \x01(\t\x12!\n\x04\x63\x61ll\x18\x02 \x01(\x0b\x32\x13.tether.v1.ToolCall\"U\n\nToolResult\x12\n\n\x02id\x18\x01 \x01(\t\x12\x14\n\x0c\x63ontent_json\x18\x02 \x01(\t\x12\x10\n\x08is_error\x18\x03 \x01(\x08\x12\x13\n\x0b\x64uration_ms\x18\x04 \x01(\x04\"5\n\rFinishRequest\x12\x0e\n\x06run_id\x18\x01 \x01(\t\x12\x14\n\x0coutcome_json\x18\x02 \x01(\t\"0\n\x05\x45vent\x12\x0b\n\x03seq\x18\x01 \x01(\x04\x12\x0c\n\x04type\x18\x02 \x01(\t\x12\x0c\n\x04json\x18\x03 \x01(\t\"T\n\tAskAnswer\x12\x0e\n\x06run_id\x18\x01 \x01(\t\x12\x13\n\x0bsubject_seq\x18\x02 \x01(\x04\x12\r\n\x05\x61llow\x18\x03 \x01(\x08\x12\x13\n\x0b\x61nswered_by\x18\x04 \x01(\t2\x86\x03\n\x06Tether\x12\x38\n\tCreateRun\x12\x1b.tether.v1.CreateRunRequest\x1a\x0e.tether.v1.Run\x12=\n\x08\x43omplete\x12\x17.tether.v1.ModelRequest\x1a\x18.tether.v1.ModelResponse\x12=\n\x08\x43\x61llTool\x12\x1a.tether.v1.ToolCallRequest\x1a\x15.tether.v1.ToolResult\x12\x34\n\x06\x46inish\x12\x18.tether.v1.FinishRequest\x1a\x10.tether.v1.Empty\x12/\n\x06\x45vents\x12\x11.tether.v1.RunRef\x1a\x10.tether.v1.Event0\x01\x12\x30\n\x06\x41nswer\x12\x14.tether.v1.AskAnswer\x1a\x10.tether.v1.Empty\x12+\n\x04Halt\x12\x11.tether.v1.RunRef\x1a\x10.tether.v1.Emptyb\x06proto3')
|
|
28
|
+
|
|
29
|
+
_globals = globals()
|
|
30
|
+
_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
|
|
31
|
+
_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'tether_pb2', _globals)
|
|
32
|
+
if not _descriptor._USE_C_DESCRIPTORS:
|
|
33
|
+
DESCRIPTOR._loaded_options = None
|
|
34
|
+
_globals['_EMPTY']._serialized_start=27
|
|
35
|
+
_globals['_EMPTY']._serialized_end=34
|
|
36
|
+
_globals['_RUNREF']._serialized_start=36
|
|
37
|
+
_globals['_RUNREF']._serialized_end=60
|
|
38
|
+
_globals['_CREATERUNREQUEST']._serialized_start=63
|
|
39
|
+
_globals['_CREATERUNREQUEST']._serialized_end=220
|
|
40
|
+
_globals['_RUN']._serialized_start=222
|
|
41
|
+
_globals['_RUN']._serialized_end=299
|
|
42
|
+
_globals['_TOOLSPEC']._serialized_start=301
|
|
43
|
+
_globals['_TOOLSPEC']._serialized_end=389
|
|
44
|
+
_globals['_MODELREQUEST']._serialized_start=391
|
|
45
|
+
_globals['_MODELREQUEST']._serialized_end=495
|
|
46
|
+
_globals['_MODELRESPONSE']._serialized_start=498
|
|
47
|
+
_globals['_MODELRESPONSE']._serialized_end=703
|
|
48
|
+
_globals['_TOOLCALL']._serialized_start=705
|
|
49
|
+
_globals['_TOOLCALL']._serialized_end=765
|
|
50
|
+
_globals['_TOOLCALLREQUEST']._serialized_start=767
|
|
51
|
+
_globals['_TOOLCALLREQUEST']._serialized_end=835
|
|
52
|
+
_globals['_TOOLRESULT']._serialized_start=837
|
|
53
|
+
_globals['_TOOLRESULT']._serialized_end=922
|
|
54
|
+
_globals['_FINISHREQUEST']._serialized_start=924
|
|
55
|
+
_globals['_FINISHREQUEST']._serialized_end=977
|
|
56
|
+
_globals['_EVENT']._serialized_start=979
|
|
57
|
+
_globals['_EVENT']._serialized_end=1027
|
|
58
|
+
_globals['_ASKANSWER']._serialized_start=1029
|
|
59
|
+
_globals['_ASKANSWER']._serialized_end=1113
|
|
60
|
+
_globals['_TETHER']._serialized_start=1116
|
|
61
|
+
_globals['_TETHER']._serialized_end=1506
|
|
62
|
+
# @@protoc_insertion_point(module_scope)
|
|
@@ -0,0 +1,370 @@
|
|
|
1
|
+
# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
|
|
2
|
+
"""Client and server classes corresponding to protobuf-defined services."""
|
|
3
|
+
import grpc
|
|
4
|
+
import warnings
|
|
5
|
+
|
|
6
|
+
from . import tether_pb2 as tether__pb2
|
|
7
|
+
|
|
8
|
+
GRPC_GENERATED_VERSION = '1.85.3'
|
|
9
|
+
GRPC_VERSION = grpc.__version__
|
|
10
|
+
_version_not_supported = False
|
|
11
|
+
|
|
12
|
+
try:
|
|
13
|
+
from grpc._utilities import first_version_is_lower
|
|
14
|
+
_version_not_supported = first_version_is_lower(GRPC_VERSION, GRPC_GENERATED_VERSION)
|
|
15
|
+
except ImportError:
|
|
16
|
+
_version_not_supported = True
|
|
17
|
+
|
|
18
|
+
if _version_not_supported:
|
|
19
|
+
raise RuntimeError(
|
|
20
|
+
f'The grpc package installed is at version {GRPC_VERSION},'
|
|
21
|
+
+ ' but the generated code in tether_pb2_grpc.py depends on'
|
|
22
|
+
+ f' grpcio>={GRPC_GENERATED_VERSION}.'
|
|
23
|
+
+ f' Please upgrade your grpc module to grpcio>={GRPC_GENERATED_VERSION}'
|
|
24
|
+
+ f' or downgrade your generated code using grpcio-tools<={GRPC_VERSION}.'
|
|
25
|
+
)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
class TetherStub:
|
|
29
|
+
"""The whole SDK surface. The agent's loop stays in the user's code; it calls
|
|
30
|
+
Complete and CallTool instead of a provider SDK and its own tool functions.
|
|
31
|
+
No logic lives in an SDK beyond type mapping.
|
|
32
|
+
"""
|
|
33
|
+
|
|
34
|
+
def __init__(self, channel):
|
|
35
|
+
"""Constructor.
|
|
36
|
+
|
|
37
|
+
Args:
|
|
38
|
+
channel: A grpc.Channel.
|
|
39
|
+
"""
|
|
40
|
+
self.CreateRun = channel.unary_unary(
|
|
41
|
+
'/tether.v1.Tether/CreateRun',
|
|
42
|
+
request_serializer=tether__pb2.CreateRunRequest.SerializeToString,
|
|
43
|
+
response_deserializer=tether__pb2.Run.FromString,
|
|
44
|
+
_registered_method=True)
|
|
45
|
+
self.Complete = channel.unary_unary(
|
|
46
|
+
'/tether.v1.Tether/Complete',
|
|
47
|
+
request_serializer=tether__pb2.ModelRequest.SerializeToString,
|
|
48
|
+
response_deserializer=tether__pb2.ModelResponse.FromString,
|
|
49
|
+
_registered_method=True)
|
|
50
|
+
self.CallTool = channel.unary_unary(
|
|
51
|
+
'/tether.v1.Tether/CallTool',
|
|
52
|
+
request_serializer=tether__pb2.ToolCallRequest.SerializeToString,
|
|
53
|
+
response_deserializer=tether__pb2.ToolResult.FromString,
|
|
54
|
+
_registered_method=True)
|
|
55
|
+
self.Finish = channel.unary_unary(
|
|
56
|
+
'/tether.v1.Tether/Finish',
|
|
57
|
+
request_serializer=tether__pb2.FinishRequest.SerializeToString,
|
|
58
|
+
response_deserializer=tether__pb2.Empty.FromString,
|
|
59
|
+
_registered_method=True)
|
|
60
|
+
self.Events = channel.unary_stream(
|
|
61
|
+
'/tether.v1.Tether/Events',
|
|
62
|
+
request_serializer=tether__pb2.RunRef.SerializeToString,
|
|
63
|
+
response_deserializer=tether__pb2.Event.FromString,
|
|
64
|
+
_registered_method=True)
|
|
65
|
+
self.Answer = channel.unary_unary(
|
|
66
|
+
'/tether.v1.Tether/Answer',
|
|
67
|
+
request_serializer=tether__pb2.AskAnswer.SerializeToString,
|
|
68
|
+
response_deserializer=tether__pb2.Empty.FromString,
|
|
69
|
+
_registered_method=True)
|
|
70
|
+
self.Halt = channel.unary_unary(
|
|
71
|
+
'/tether.v1.Tether/Halt',
|
|
72
|
+
request_serializer=tether__pb2.RunRef.SerializeToString,
|
|
73
|
+
response_deserializer=tether__pb2.Empty.FromString,
|
|
74
|
+
_registered_method=True)
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
class TetherServicer:
|
|
78
|
+
"""The whole SDK surface. The agent's loop stays in the user's code; it calls
|
|
79
|
+
Complete and CallTool instead of a provider SDK and its own tool functions.
|
|
80
|
+
No logic lives in an SDK beyond type mapping.
|
|
81
|
+
"""
|
|
82
|
+
|
|
83
|
+
def CreateRun(self, request, context):
|
|
84
|
+
"""Missing associated documentation comment in .proto file."""
|
|
85
|
+
context.set_code(grpc.StatusCode.UNIMPLEMENTED)
|
|
86
|
+
context.set_details('Method not implemented!')
|
|
87
|
+
raise NotImplementedError('Method not implemented!')
|
|
88
|
+
|
|
89
|
+
def Complete(self, request, context):
|
|
90
|
+
"""Agent asks for a model turn.
|
|
91
|
+
"""
|
|
92
|
+
context.set_code(grpc.StatusCode.UNIMPLEMENTED)
|
|
93
|
+
context.set_details('Method not implemented!')
|
|
94
|
+
raise NotImplementedError('Method not implemented!')
|
|
95
|
+
|
|
96
|
+
def CallTool(self, request, context):
|
|
97
|
+
"""Agent asks for a tool. Policy, sandbox and trace all happen here.
|
|
98
|
+
"""
|
|
99
|
+
context.set_code(grpc.StatusCode.UNIMPLEMENTED)
|
|
100
|
+
context.set_details('Method not implemented!')
|
|
101
|
+
raise NotImplementedError('Method not implemented!')
|
|
102
|
+
|
|
103
|
+
def Finish(self, request, context):
|
|
104
|
+
"""The agent is done. Records run.finished and closes the trace.
|
|
105
|
+
"""
|
|
106
|
+
context.set_code(grpc.StatusCode.UNIMPLEMENTED)
|
|
107
|
+
context.set_details('Method not implemented!')
|
|
108
|
+
raise NotImplementedError('Method not implemented!')
|
|
109
|
+
|
|
110
|
+
def Events(self, request, context):
|
|
111
|
+
"""Tail the trace: every event so far, then each new one until the run ends.
|
|
112
|
+
"""
|
|
113
|
+
context.set_code(grpc.StatusCode.UNIMPLEMENTED)
|
|
114
|
+
context.set_details('Method not implemented!')
|
|
115
|
+
raise NotImplementedError('Method not implemented!')
|
|
116
|
+
|
|
117
|
+
def Answer(self, request, context):
|
|
118
|
+
"""Resolve a policy.ask. The Complete or CallTool that asked is waiting.
|
|
119
|
+
"""
|
|
120
|
+
context.set_code(grpc.StatusCode.UNIMPLEMENTED)
|
|
121
|
+
context.set_details('Method not implemented!')
|
|
122
|
+
raise NotImplementedError('Method not implemented!')
|
|
123
|
+
|
|
124
|
+
def Halt(self, request, context):
|
|
125
|
+
"""Trip the run's kill switch. It halts at its next event boundary.
|
|
126
|
+
"""
|
|
127
|
+
context.set_code(grpc.StatusCode.UNIMPLEMENTED)
|
|
128
|
+
context.set_details('Method not implemented!')
|
|
129
|
+
raise NotImplementedError('Method not implemented!')
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
def add_TetherServicer_to_server(servicer, server):
|
|
133
|
+
rpc_method_handlers = {
|
|
134
|
+
'CreateRun': grpc.unary_unary_rpc_method_handler(
|
|
135
|
+
servicer.CreateRun,
|
|
136
|
+
request_deserializer=tether__pb2.CreateRunRequest.FromString,
|
|
137
|
+
response_serializer=tether__pb2.Run.SerializeToString,
|
|
138
|
+
),
|
|
139
|
+
'Complete': grpc.unary_unary_rpc_method_handler(
|
|
140
|
+
servicer.Complete,
|
|
141
|
+
request_deserializer=tether__pb2.ModelRequest.FromString,
|
|
142
|
+
response_serializer=tether__pb2.ModelResponse.SerializeToString,
|
|
143
|
+
),
|
|
144
|
+
'CallTool': grpc.unary_unary_rpc_method_handler(
|
|
145
|
+
servicer.CallTool,
|
|
146
|
+
request_deserializer=tether__pb2.ToolCallRequest.FromString,
|
|
147
|
+
response_serializer=tether__pb2.ToolResult.SerializeToString,
|
|
148
|
+
),
|
|
149
|
+
'Finish': grpc.unary_unary_rpc_method_handler(
|
|
150
|
+
servicer.Finish,
|
|
151
|
+
request_deserializer=tether__pb2.FinishRequest.FromString,
|
|
152
|
+
response_serializer=tether__pb2.Empty.SerializeToString,
|
|
153
|
+
),
|
|
154
|
+
'Events': grpc.unary_stream_rpc_method_handler(
|
|
155
|
+
servicer.Events,
|
|
156
|
+
request_deserializer=tether__pb2.RunRef.FromString,
|
|
157
|
+
response_serializer=tether__pb2.Event.SerializeToString,
|
|
158
|
+
),
|
|
159
|
+
'Answer': grpc.unary_unary_rpc_method_handler(
|
|
160
|
+
servicer.Answer,
|
|
161
|
+
request_deserializer=tether__pb2.AskAnswer.FromString,
|
|
162
|
+
response_serializer=tether__pb2.Empty.SerializeToString,
|
|
163
|
+
),
|
|
164
|
+
'Halt': grpc.unary_unary_rpc_method_handler(
|
|
165
|
+
servicer.Halt,
|
|
166
|
+
request_deserializer=tether__pb2.RunRef.FromString,
|
|
167
|
+
response_serializer=tether__pb2.Empty.SerializeToString,
|
|
168
|
+
),
|
|
169
|
+
}
|
|
170
|
+
generic_handler = grpc.method_handlers_generic_handler(
|
|
171
|
+
'tether.v1.Tether', rpc_method_handlers)
|
|
172
|
+
server.add_generic_rpc_handlers((generic_handler,))
|
|
173
|
+
server.add_registered_method_handlers('tether.v1.Tether', rpc_method_handlers)
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
# This class is part of an EXPERIMENTAL API.
|
|
177
|
+
class Tether:
|
|
178
|
+
"""The whole SDK surface. The agent's loop stays in the user's code; it calls
|
|
179
|
+
Complete and CallTool instead of a provider SDK and its own tool functions.
|
|
180
|
+
No logic lives in an SDK beyond type mapping.
|
|
181
|
+
"""
|
|
182
|
+
|
|
183
|
+
@staticmethod
|
|
184
|
+
def CreateRun(request,
|
|
185
|
+
target,
|
|
186
|
+
options=(),
|
|
187
|
+
channel_credentials=None,
|
|
188
|
+
call_credentials=None,
|
|
189
|
+
insecure=False,
|
|
190
|
+
compression=None,
|
|
191
|
+
wait_for_ready=None,
|
|
192
|
+
timeout=None,
|
|
193
|
+
metadata=None):
|
|
194
|
+
return grpc.experimental.unary_unary(
|
|
195
|
+
request,
|
|
196
|
+
target,
|
|
197
|
+
'/tether.v1.Tether/CreateRun',
|
|
198
|
+
tether__pb2.CreateRunRequest.SerializeToString,
|
|
199
|
+
tether__pb2.Run.FromString,
|
|
200
|
+
options,
|
|
201
|
+
channel_credentials,
|
|
202
|
+
insecure,
|
|
203
|
+
call_credentials,
|
|
204
|
+
compression,
|
|
205
|
+
wait_for_ready,
|
|
206
|
+
timeout,
|
|
207
|
+
metadata,
|
|
208
|
+
_registered_method=True)
|
|
209
|
+
|
|
210
|
+
@staticmethod
|
|
211
|
+
def Complete(request,
|
|
212
|
+
target,
|
|
213
|
+
options=(),
|
|
214
|
+
channel_credentials=None,
|
|
215
|
+
call_credentials=None,
|
|
216
|
+
insecure=False,
|
|
217
|
+
compression=None,
|
|
218
|
+
wait_for_ready=None,
|
|
219
|
+
timeout=None,
|
|
220
|
+
metadata=None):
|
|
221
|
+
return grpc.experimental.unary_unary(
|
|
222
|
+
request,
|
|
223
|
+
target,
|
|
224
|
+
'/tether.v1.Tether/Complete',
|
|
225
|
+
tether__pb2.ModelRequest.SerializeToString,
|
|
226
|
+
tether__pb2.ModelResponse.FromString,
|
|
227
|
+
options,
|
|
228
|
+
channel_credentials,
|
|
229
|
+
insecure,
|
|
230
|
+
call_credentials,
|
|
231
|
+
compression,
|
|
232
|
+
wait_for_ready,
|
|
233
|
+
timeout,
|
|
234
|
+
metadata,
|
|
235
|
+
_registered_method=True)
|
|
236
|
+
|
|
237
|
+
@staticmethod
|
|
238
|
+
def CallTool(request,
|
|
239
|
+
target,
|
|
240
|
+
options=(),
|
|
241
|
+
channel_credentials=None,
|
|
242
|
+
call_credentials=None,
|
|
243
|
+
insecure=False,
|
|
244
|
+
compression=None,
|
|
245
|
+
wait_for_ready=None,
|
|
246
|
+
timeout=None,
|
|
247
|
+
metadata=None):
|
|
248
|
+
return grpc.experimental.unary_unary(
|
|
249
|
+
request,
|
|
250
|
+
target,
|
|
251
|
+
'/tether.v1.Tether/CallTool',
|
|
252
|
+
tether__pb2.ToolCallRequest.SerializeToString,
|
|
253
|
+
tether__pb2.ToolResult.FromString,
|
|
254
|
+
options,
|
|
255
|
+
channel_credentials,
|
|
256
|
+
insecure,
|
|
257
|
+
call_credentials,
|
|
258
|
+
compression,
|
|
259
|
+
wait_for_ready,
|
|
260
|
+
timeout,
|
|
261
|
+
metadata,
|
|
262
|
+
_registered_method=True)
|
|
263
|
+
|
|
264
|
+
@staticmethod
|
|
265
|
+
def Finish(request,
|
|
266
|
+
target,
|
|
267
|
+
options=(),
|
|
268
|
+
channel_credentials=None,
|
|
269
|
+
call_credentials=None,
|
|
270
|
+
insecure=False,
|
|
271
|
+
compression=None,
|
|
272
|
+
wait_for_ready=None,
|
|
273
|
+
timeout=None,
|
|
274
|
+
metadata=None):
|
|
275
|
+
return grpc.experimental.unary_unary(
|
|
276
|
+
request,
|
|
277
|
+
target,
|
|
278
|
+
'/tether.v1.Tether/Finish',
|
|
279
|
+
tether__pb2.FinishRequest.SerializeToString,
|
|
280
|
+
tether__pb2.Empty.FromString,
|
|
281
|
+
options,
|
|
282
|
+
channel_credentials,
|
|
283
|
+
insecure,
|
|
284
|
+
call_credentials,
|
|
285
|
+
compression,
|
|
286
|
+
wait_for_ready,
|
|
287
|
+
timeout,
|
|
288
|
+
metadata,
|
|
289
|
+
_registered_method=True)
|
|
290
|
+
|
|
291
|
+
@staticmethod
|
|
292
|
+
def Events(request,
|
|
293
|
+
target,
|
|
294
|
+
options=(),
|
|
295
|
+
channel_credentials=None,
|
|
296
|
+
call_credentials=None,
|
|
297
|
+
insecure=False,
|
|
298
|
+
compression=None,
|
|
299
|
+
wait_for_ready=None,
|
|
300
|
+
timeout=None,
|
|
301
|
+
metadata=None):
|
|
302
|
+
return grpc.experimental.unary_stream(
|
|
303
|
+
request,
|
|
304
|
+
target,
|
|
305
|
+
'/tether.v1.Tether/Events',
|
|
306
|
+
tether__pb2.RunRef.SerializeToString,
|
|
307
|
+
tether__pb2.Event.FromString,
|
|
308
|
+
options,
|
|
309
|
+
channel_credentials,
|
|
310
|
+
insecure,
|
|
311
|
+
call_credentials,
|
|
312
|
+
compression,
|
|
313
|
+
wait_for_ready,
|
|
314
|
+
timeout,
|
|
315
|
+
metadata,
|
|
316
|
+
_registered_method=True)
|
|
317
|
+
|
|
318
|
+
@staticmethod
|
|
319
|
+
def Answer(request,
|
|
320
|
+
target,
|
|
321
|
+
options=(),
|
|
322
|
+
channel_credentials=None,
|
|
323
|
+
call_credentials=None,
|
|
324
|
+
insecure=False,
|
|
325
|
+
compression=None,
|
|
326
|
+
wait_for_ready=None,
|
|
327
|
+
timeout=None,
|
|
328
|
+
metadata=None):
|
|
329
|
+
return grpc.experimental.unary_unary(
|
|
330
|
+
request,
|
|
331
|
+
target,
|
|
332
|
+
'/tether.v1.Tether/Answer',
|
|
333
|
+
tether__pb2.AskAnswer.SerializeToString,
|
|
334
|
+
tether__pb2.Empty.FromString,
|
|
335
|
+
options,
|
|
336
|
+
channel_credentials,
|
|
337
|
+
insecure,
|
|
338
|
+
call_credentials,
|
|
339
|
+
compression,
|
|
340
|
+
wait_for_ready,
|
|
341
|
+
timeout,
|
|
342
|
+
metadata,
|
|
343
|
+
_registered_method=True)
|
|
344
|
+
|
|
345
|
+
@staticmethod
|
|
346
|
+
def Halt(request,
|
|
347
|
+
target,
|
|
348
|
+
options=(),
|
|
349
|
+
channel_credentials=None,
|
|
350
|
+
call_credentials=None,
|
|
351
|
+
insecure=False,
|
|
352
|
+
compression=None,
|
|
353
|
+
wait_for_ready=None,
|
|
354
|
+
timeout=None,
|
|
355
|
+
metadata=None):
|
|
356
|
+
return grpc.experimental.unary_unary(
|
|
357
|
+
request,
|
|
358
|
+
target,
|
|
359
|
+
'/tether.v1.Tether/Halt',
|
|
360
|
+
tether__pb2.RunRef.SerializeToString,
|
|
361
|
+
tether__pb2.Empty.FromString,
|
|
362
|
+
options,
|
|
363
|
+
channel_credentials,
|
|
364
|
+
insecure,
|
|
365
|
+
call_credentials,
|
|
366
|
+
compression,
|
|
367
|
+
wait_for_ready,
|
|
368
|
+
timeout,
|
|
369
|
+
metadata,
|
|
370
|
+
_registered_method=True)
|
tether/_run.py
ADDED
|
@@ -0,0 +1,381 @@
|
|
|
1
|
+
"""The client: one class, one gRPC request per method."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
import os
|
|
7
|
+
import shutil
|
|
8
|
+
import subprocess
|
|
9
|
+
import time
|
|
10
|
+
from dataclasses import dataclass
|
|
11
|
+
from pathlib import Path
|
|
12
|
+
from typing import Any, Iterator, Optional, Sequence, Union
|
|
13
|
+
|
|
14
|
+
import grpc
|
|
15
|
+
|
|
16
|
+
from ._proto import tether_pb2 as pb
|
|
17
|
+
from ._proto import tether_pb2_grpc as pb_grpc
|
|
18
|
+
|
|
19
|
+
DEFAULT_DIR = ".tether"
|
|
20
|
+
|
|
21
|
+
# How long to wait for a daemon this client started to answer on its socket.
|
|
22
|
+
_DAEMON_START_SECS = 10.0
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
class TetherError(RuntimeError):
|
|
26
|
+
"""A call the daemon refused. ``code`` is the gRPC status code."""
|
|
27
|
+
|
|
28
|
+
def __init__(self, code: grpc.StatusCode, message: str) -> None:
|
|
29
|
+
super().__init__(message)
|
|
30
|
+
self.code = code
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
class Halted(TetherError):
|
|
34
|
+
"""The run is halted or finished and takes no more calls.
|
|
35
|
+
|
|
36
|
+
Tether halts a run when a budget is spent, a policy ask goes unanswered,
|
|
37
|
+
the kill switch is tripped or the model fails. The message says which.
|
|
38
|
+
"""
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
@dataclass(frozen=True)
|
|
42
|
+
class Tool:
|
|
43
|
+
"""A tool the run offers, as listed when the run started."""
|
|
44
|
+
|
|
45
|
+
name: str
|
|
46
|
+
server: str
|
|
47
|
+
description: str
|
|
48
|
+
input_schema: Any
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
@dataclass(frozen=True)
|
|
52
|
+
class ToolCall:
|
|
53
|
+
"""A tool the model asked for."""
|
|
54
|
+
|
|
55
|
+
id: str
|
|
56
|
+
name: str
|
|
57
|
+
arguments: Any
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
@dataclass(frozen=True)
|
|
61
|
+
class ToolResult:
|
|
62
|
+
"""What a tool call came to.
|
|
63
|
+
|
|
64
|
+
A call that policy denied comes back here with ``is_error`` set, like any
|
|
65
|
+
other failed call. It does not raise.
|
|
66
|
+
"""
|
|
67
|
+
|
|
68
|
+
id: str
|
|
69
|
+
content: Any
|
|
70
|
+
is_error: bool
|
|
71
|
+
duration_ms: int
|
|
72
|
+
|
|
73
|
+
def block(self) -> dict:
|
|
74
|
+
"""This result as a content block for the next request's history."""
|
|
75
|
+
return {
|
|
76
|
+
"type": "tool_result",
|
|
77
|
+
"id": self.id,
|
|
78
|
+
"content": self.content,
|
|
79
|
+
"is_error": self.is_error,
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
@dataclass(frozen=True)
|
|
84
|
+
class Reply:
|
|
85
|
+
"""One model turn.
|
|
86
|
+
|
|
87
|
+
Append ``message`` to your history exactly as it is. It can hold blocks
|
|
88
|
+
only the provider understands, which must go back unchanged. Look at
|
|
89
|
+
``stop_reason`` before acting: ``refusal`` and ``max_tokens`` are replies
|
|
90
|
+
that are not finished answers.
|
|
91
|
+
"""
|
|
92
|
+
|
|
93
|
+
message: dict
|
|
94
|
+
tool_calls: list
|
|
95
|
+
stop_reason: Optional[str]
|
|
96
|
+
input_tokens: int
|
|
97
|
+
output_tokens: int
|
|
98
|
+
cache_read_tokens: int
|
|
99
|
+
cache_write_tokens: int
|
|
100
|
+
|
|
101
|
+
@property
|
|
102
|
+
def text(self) -> str:
|
|
103
|
+
"""The reply's text blocks, joined."""
|
|
104
|
+
blocks = self.message.get("content", [])
|
|
105
|
+
return "".join(b.get("text", "") for b in blocks if b.get("type") == "text")
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
@dataclass(frozen=True)
|
|
109
|
+
class Event:
|
|
110
|
+
"""One event of the trace."""
|
|
111
|
+
|
|
112
|
+
seq: int
|
|
113
|
+
type: str
|
|
114
|
+
data: dict
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def user(text: str) -> dict:
|
|
118
|
+
"""A user message holding ``text``."""
|
|
119
|
+
return {"role": "user", "content": [{"type": "text", "text": text}]}
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
def system(text: str) -> dict:
|
|
123
|
+
"""A system message holding ``text``. Put it first to make it the system prompt."""
|
|
124
|
+
return {"role": "system", "content": [{"type": "text", "text": text}]}
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
def tool_results(results: Sequence[ToolResult]) -> dict:
|
|
128
|
+
"""The message that hands a turn's tool results back to the model."""
|
|
129
|
+
return {"role": "tool", "content": [result.block() for result in results]}
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
def _raise(error: grpc.RpcError) -> None:
|
|
133
|
+
code, message = error.code(), error.details() or ""
|
|
134
|
+
if code == grpc.StatusCode.FAILED_PRECONDITION:
|
|
135
|
+
raise Halted(code, message) from None
|
|
136
|
+
raise TetherError(code, message) from None
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
def _daemon_command() -> list:
|
|
140
|
+
"""The command that starts the daemon: ``tetherd``, or ``tether daemon``."""
|
|
141
|
+
override = os.environ.get("TETHERD")
|
|
142
|
+
if override:
|
|
143
|
+
return [override]
|
|
144
|
+
if shutil.which("tetherd"):
|
|
145
|
+
return ["tetherd"]
|
|
146
|
+
if shutil.which("tether"):
|
|
147
|
+
return ["tether", "daemon"]
|
|
148
|
+
raise TetherError(
|
|
149
|
+
grpc.StatusCode.UNAVAILABLE,
|
|
150
|
+
"no daemon is running and neither tetherd nor tether is on PATH; "
|
|
151
|
+
"set TETHERD to the tetherd binary",
|
|
152
|
+
)
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def _connect(socket: Path) -> grpc.Channel:
|
|
156
|
+
"""A channel to the daemon on ``socket``, starting the daemon if needed."""
|
|
157
|
+
|
|
158
|
+
def ready(channel: grpc.Channel, seconds: float) -> bool:
|
|
159
|
+
try:
|
|
160
|
+
grpc.channel_ready_future(channel).result(timeout=seconds)
|
|
161
|
+
return True
|
|
162
|
+
except grpc.FutureTimeoutError:
|
|
163
|
+
return False
|
|
164
|
+
|
|
165
|
+
target = f"unix:{socket}"
|
|
166
|
+
# Over a Unix socket gRPC would send the socket's path as the HTTP/2
|
|
167
|
+
# authority, which the daemon's HTTP stack rejects. Name one instead.
|
|
168
|
+
options = [("grpc.default_authority", "localhost")]
|
|
169
|
+
channel = grpc.insecure_channel(target, options)
|
|
170
|
+
if socket.exists() and ready(channel, 1.0):
|
|
171
|
+
return channel
|
|
172
|
+
channel.close()
|
|
173
|
+
|
|
174
|
+
socket.parent.mkdir(parents=True, exist_ok=True)
|
|
175
|
+
with open(socket.parent / "tetherd.log", "ab") as log:
|
|
176
|
+
subprocess.Popen(
|
|
177
|
+
_daemon_command() + ["--socket", str(socket)],
|
|
178
|
+
stdin=subprocess.DEVNULL,
|
|
179
|
+
stdout=log,
|
|
180
|
+
stderr=log,
|
|
181
|
+
# Its own session, so it outlives this process and its Ctrl-C.
|
|
182
|
+
start_new_session=True,
|
|
183
|
+
)
|
|
184
|
+
deadline = time.monotonic() + _DAEMON_START_SECS
|
|
185
|
+
while time.monotonic() < deadline:
|
|
186
|
+
if socket.exists():
|
|
187
|
+
channel = grpc.insecure_channel(target, options)
|
|
188
|
+
if ready(channel, 1.0):
|
|
189
|
+
return channel
|
|
190
|
+
channel.close()
|
|
191
|
+
time.sleep(0.05)
|
|
192
|
+
raise TetherError(
|
|
193
|
+
grpc.StatusCode.UNAVAILABLE,
|
|
194
|
+
f"the daemon did not come up on {socket}; see {socket.parent / 'tetherd.log'}",
|
|
195
|
+
)
|
|
196
|
+
|
|
197
|
+
|
|
198
|
+
class Run:
|
|
199
|
+
"""A run under Tether.
|
|
200
|
+
|
|
201
|
+
Creating one starts the run. Use it as a context manager: leaving the
|
|
202
|
+
block finishes the run, or halts it if the block raised.
|
|
203
|
+
|
|
204
|
+
``policy`` is the path of a ``tether.toml``; without one there are no
|
|
205
|
+
rules and every tool call asks. ``provider`` is ``"anthropic"``,
|
|
206
|
+
``"openai_compat"`` for a server with an OpenAI-style chat completions
|
|
207
|
+
endpoint (``OPENAI_BASE_URL``, ``OPENAI_API_KEY``) or, for tests and demos, ``"fake"`` with ``script`` naming a file of scripted
|
|
208
|
+
replies. ``dir`` is where the trace goes. Unset arguments fall back to
|
|
209
|
+
``TETHER_POLICY``, ``TETHER_DIR`` and ``TETHER_SOCKET``, which
|
|
210
|
+
``tether run -- <command>`` sets.
|
|
211
|
+
"""
|
|
212
|
+
|
|
213
|
+
def __init__(
|
|
214
|
+
self,
|
|
215
|
+
*,
|
|
216
|
+
policy: Union[str, os.PathLike, None] = None,
|
|
217
|
+
provider: str = "anthropic",
|
|
218
|
+
script: Union[str, os.PathLike, None] = None,
|
|
219
|
+
dir: Union[str, os.PathLike, None] = None,
|
|
220
|
+
workspace: Union[str, os.PathLike, None] = None,
|
|
221
|
+
agent: str = "main",
|
|
222
|
+
betas: Sequence[str] = (),
|
|
223
|
+
socket: Union[str, os.PathLike, None] = None,
|
|
224
|
+
) -> None:
|
|
225
|
+
# The daemon may have another working directory: send absolute paths.
|
|
226
|
+
def absolute(path: Union[str, os.PathLike, None]) -> str:
|
|
227
|
+
return str(Path(path).resolve()) if path else ""
|
|
228
|
+
|
|
229
|
+
run_dir = Path(dir or os.environ.get("TETHER_DIR") or DEFAULT_DIR).resolve()
|
|
230
|
+
socket_path = Path(
|
|
231
|
+
socket or os.environ.get("TETHER_SOCKET") or run_dir / "tetherd.sock"
|
|
232
|
+
).resolve()
|
|
233
|
+
self._channel = _connect(socket_path)
|
|
234
|
+
self._stub = pb_grpc.TetherStub(self._channel)
|
|
235
|
+
self._over = False
|
|
236
|
+
try:
|
|
237
|
+
created = self._stub.CreateRun(
|
|
238
|
+
pb.CreateRunRequest(
|
|
239
|
+
agent=agent,
|
|
240
|
+
policy_path=absolute(policy or os.environ.get("TETHER_POLICY")),
|
|
241
|
+
workspace=absolute(workspace),
|
|
242
|
+
provider=provider,
|
|
243
|
+
script_path=absolute(script),
|
|
244
|
+
dir=str(run_dir),
|
|
245
|
+
betas=list(betas),
|
|
246
|
+
)
|
|
247
|
+
)
|
|
248
|
+
except grpc.RpcError as error:
|
|
249
|
+
self._channel.close()
|
|
250
|
+
_raise(error)
|
|
251
|
+
self.id: str = created.run_id
|
|
252
|
+
self.trace_path: str = created.trace_path
|
|
253
|
+
self.tools: list = [
|
|
254
|
+
Tool(t.name, t.server, t.description, json.loads(t.input_schema_json))
|
|
255
|
+
for t in created.tools
|
|
256
|
+
]
|
|
257
|
+
|
|
258
|
+
def complete(
|
|
259
|
+
self,
|
|
260
|
+
*,
|
|
261
|
+
model: str,
|
|
262
|
+
messages: Sequence[dict],
|
|
263
|
+
tools: Optional[Sequence[str]] = None,
|
|
264
|
+
params: Optional[dict] = None,
|
|
265
|
+
) -> Reply:
|
|
266
|
+
"""Ask the model for its next turn.
|
|
267
|
+
|
|
268
|
+
``messages`` is the whole history. ``tools`` names the tools to
|
|
269
|
+
offer; by default all of the run's. ``params`` is passed to the
|
|
270
|
+
provider as the request's other fields (``max_tokens``,
|
|
271
|
+
``output_config`` and so on).
|
|
272
|
+
"""
|
|
273
|
+
names = [tool.name for tool in self.tools] if tools is None else list(tools)
|
|
274
|
+
try:
|
|
275
|
+
response = self._stub.Complete(
|
|
276
|
+
pb.ModelRequest(
|
|
277
|
+
run_id=self.id,
|
|
278
|
+
model=model,
|
|
279
|
+
messages_json=json.dumps(list(messages)),
|
|
280
|
+
tools=names,
|
|
281
|
+
params_json=json.dumps(params) if params else "",
|
|
282
|
+
)
|
|
283
|
+
)
|
|
284
|
+
except grpc.RpcError as error:
|
|
285
|
+
self._over = error.code() == grpc.StatusCode.FAILED_PRECONDITION
|
|
286
|
+
_raise(error)
|
|
287
|
+
return Reply(
|
|
288
|
+
message=json.loads(response.message_json),
|
|
289
|
+
tool_calls=[
|
|
290
|
+
ToolCall(c.id, c.name, json.loads(c.arguments_json))
|
|
291
|
+
for c in response.tool_calls
|
|
292
|
+
],
|
|
293
|
+
stop_reason=response.stop_reason or None,
|
|
294
|
+
input_tokens=response.input_tokens,
|
|
295
|
+
output_tokens=response.output_tokens,
|
|
296
|
+
cache_read_tokens=response.cache_read_tokens,
|
|
297
|
+
cache_write_tokens=response.cache_write_tokens,
|
|
298
|
+
)
|
|
299
|
+
|
|
300
|
+
def call_tool(self, call: ToolCall) -> ToolResult:
|
|
301
|
+
"""Run a tool the model asked for, through policy and the sandbox."""
|
|
302
|
+
try:
|
|
303
|
+
result = self._stub.CallTool(
|
|
304
|
+
pb.ToolCallRequest(
|
|
305
|
+
run_id=self.id,
|
|
306
|
+
call=pb.ToolCall(
|
|
307
|
+
id=call.id,
|
|
308
|
+
name=call.name,
|
|
309
|
+
arguments_json=json.dumps(call.arguments),
|
|
310
|
+
),
|
|
311
|
+
)
|
|
312
|
+
)
|
|
313
|
+
except grpc.RpcError as error:
|
|
314
|
+
self._over = error.code() == grpc.StatusCode.FAILED_PRECONDITION
|
|
315
|
+
_raise(error)
|
|
316
|
+
return ToolResult(
|
|
317
|
+
id=result.id,
|
|
318
|
+
content=json.loads(result.content_json),
|
|
319
|
+
is_error=result.is_error,
|
|
320
|
+
duration_ms=result.duration_ms,
|
|
321
|
+
)
|
|
322
|
+
|
|
323
|
+
def finish(self, outcome: Any = None) -> None:
|
|
324
|
+
"""Say the agent is done. ``outcome`` is recorded in the trace."""
|
|
325
|
+
try:
|
|
326
|
+
self._stub.Finish(
|
|
327
|
+
pb.FinishRequest(run_id=self.id, outcome_json=json.dumps(outcome))
|
|
328
|
+
)
|
|
329
|
+
except grpc.RpcError as error:
|
|
330
|
+
_raise(error)
|
|
331
|
+
finally:
|
|
332
|
+
self._over = True
|
|
333
|
+
|
|
334
|
+
def halt(self) -> None:
|
|
335
|
+
"""Trip the run's kill switch."""
|
|
336
|
+
try:
|
|
337
|
+
self._stub.Halt(pb.RunRef(run_id=self.id))
|
|
338
|
+
except grpc.RpcError as error:
|
|
339
|
+
_raise(error)
|
|
340
|
+
finally:
|
|
341
|
+
self._over = True
|
|
342
|
+
|
|
343
|
+
def answer(self, subject_seq: int, allow: bool, answered_by: str = "sdk") -> None:
|
|
344
|
+
"""Answer a policy ask. The call that asked is waiting in another thread."""
|
|
345
|
+
try:
|
|
346
|
+
self._stub.Answer(
|
|
347
|
+
pb.AskAnswer(
|
|
348
|
+
run_id=self.id,
|
|
349
|
+
subject_seq=subject_seq,
|
|
350
|
+
allow=allow,
|
|
351
|
+
answered_by=answered_by,
|
|
352
|
+
)
|
|
353
|
+
)
|
|
354
|
+
except grpc.RpcError as error:
|
|
355
|
+
_raise(error)
|
|
356
|
+
|
|
357
|
+
def events(self) -> Iterator[Event]:
|
|
358
|
+
"""The trace so far, then each new event until the run ends."""
|
|
359
|
+
try:
|
|
360
|
+
for event in self._stub.Events(pb.RunRef(run_id=self.id)):
|
|
361
|
+
yield Event(event.seq, event.type, json.loads(event.json))
|
|
362
|
+
except grpc.RpcError as error:
|
|
363
|
+
_raise(error)
|
|
364
|
+
|
|
365
|
+
def close(self) -> None:
|
|
366
|
+
"""Close the connection. The run itself is not affected."""
|
|
367
|
+
self._channel.close()
|
|
368
|
+
|
|
369
|
+
def __enter__(self) -> "Run":
|
|
370
|
+
return self
|
|
371
|
+
|
|
372
|
+
def __exit__(self, exc_type, exc, traceback) -> None:
|
|
373
|
+
try:
|
|
374
|
+
if not self._over:
|
|
375
|
+
# Left without a word: done if the block ended, stopped if it raised.
|
|
376
|
+
if exc_type is None:
|
|
377
|
+
self.finish()
|
|
378
|
+
else:
|
|
379
|
+
self.halt()
|
|
380
|
+
finally:
|
|
381
|
+
self.close()
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: tether-agents
|
|
3
|
+
Version: 0.3.0
|
|
4
|
+
Summary: Python client for Tether: run agents you don't trust on infrastructure you do.
|
|
5
|
+
Project-URL: Repository, https://github.com/chizy7/tether
|
|
6
|
+
License-Expression: Apache-2.0
|
|
7
|
+
Requires-Python: >=3.9
|
|
8
|
+
Requires-Dist: grpcio>=1.85.3
|
|
9
|
+
Requires-Dist: protobuf<8,>=7.35.1
|
|
10
|
+
Provides-Extra: dev
|
|
11
|
+
Requires-Dist: grpcio-tools==1.85.3; extra == 'dev'
|
|
12
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
13
|
+
Description-Content-Type: text/markdown
|
|
14
|
+
|
|
15
|
+
# tether-agents
|
|
16
|
+
|
|
17
|
+
Python client for [Tether](https://github.com/chizy7/tether/tree/master/README.md). Your agent keeps its own loop;
|
|
18
|
+
it calls `run.complete` where it called its provider SDK and `run.call_tool`
|
|
19
|
+
where it ran a tool, and Tether does the rest: policy, sandbox, budgets and
|
|
20
|
+
the trace.
|
|
21
|
+
|
|
22
|
+
```python
|
|
23
|
+
import tether
|
|
24
|
+
|
|
25
|
+
with tether.Run(policy="tether.toml") as run:
|
|
26
|
+
messages = [tether.user("Write hello.txt, then show me what is in it.")]
|
|
27
|
+
while True:
|
|
28
|
+
reply = run.complete(model="claude-opus-5-5", messages=messages)
|
|
29
|
+
messages.append(reply.message)
|
|
30
|
+
if not reply.tool_calls:
|
|
31
|
+
run.finish(reply.text)
|
|
32
|
+
break
|
|
33
|
+
results = [run.call_tool(call) for call in reply.tool_calls]
|
|
34
|
+
messages.append(tether.tool_results(results))
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
A complete example is in [examples/raw-loop-py](https://github.com/chizy7/tether/tree/master/examples/raw-loop-py).
|
|
38
|
+
|
|
39
|
+
## Install
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
pip install tether-agents
|
|
43
|
+
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/chizy7/tether/releases/latest/download/tether-cli-installer.sh | sh
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
The second line installs the `tether` binary, which carries the daemon the
|
|
47
|
+
SDK talks to. The SDK and the binary should be the same version.
|
|
48
|
+
|
|
49
|
+
To work on the SDK, from a checkout of the repository:
|
|
50
|
+
|
|
51
|
+
```
|
|
52
|
+
pip install -e sdks/python
|
|
53
|
+
cargo build -p tetherd # the daemon the SDK talks to
|
|
54
|
+
export PATH="$PWD/target/debug:$PATH"
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## How it works
|
|
58
|
+
|
|
59
|
+
The SDK is a thin client for the daemon, `tetherd`, over gRPC on a Unix
|
|
60
|
+
socket. Each method is one request and nothing in the SDK decides anything.
|
|
61
|
+
|
|
62
|
+
`tether.Run(...)` connects to the socket and starts a run. If no daemon
|
|
63
|
+
answers, it starts one: `$TETHERD` if set, else `tetherd` or `tether daemon`
|
|
64
|
+
from `PATH`. The daemon logs to `tetherd.log` beside the socket and exits by
|
|
65
|
+
itself a few seconds after its last run.
|
|
66
|
+
|
|
67
|
+
| | |
|
|
68
|
+
| --- | --- |
|
|
69
|
+
| `Run(policy=, provider=, script=, dir=, workspace=, agent=, betas=, socket=)` | Start a run. `provider` is `"anthropic"`, `"openai_compat"` (any server with an OpenAI-style `/chat/completions`, set by `OPENAI_BASE_URL` and `OPENAI_API_KEY`) or, with `script`, `"fake"` |
|
|
70
|
+
| `run.tools` | The tools the run offers |
|
|
71
|
+
| `run.complete(model=, messages=, tools=, params=)` | One model turn. Returns a `Reply` |
|
|
72
|
+
| `run.call_tool(call)` | Run a tool the model asked for. Returns a `ToolResult` |
|
|
73
|
+
| `run.finish(outcome)` | The agent is done |
|
|
74
|
+
| `run.halt()` | Trip the run's kill switch |
|
|
75
|
+
| `run.answer(subject_seq, allow)` | Answer a policy ask, from another thread |
|
|
76
|
+
| `run.events()` | Iterate the trace as it is written |
|
|
77
|
+
| `run.id`, `run.trace_path` | The run's id and where its trace is |
|
|
78
|
+
|
|
79
|
+
Used as a context manager, a run that leaves its block without a word is
|
|
80
|
+
finished, or halted if the block raised.
|
|
81
|
+
|
|
82
|
+
Things to know:
|
|
83
|
+
|
|
84
|
+
- Append `reply.message` to your history exactly as it is. It can hold blocks
|
|
85
|
+
only the provider understands, such as reasoning blocks, which must go back
|
|
86
|
+
unchanged.
|
|
87
|
+
- Check `reply.stop_reason` before acting. `refusal` and `max_tokens` are
|
|
88
|
+
replies that are not finished answers.
|
|
89
|
+
- A tool call that policy denies does not raise. It comes back as a
|
|
90
|
+
`ToolResult` with `is_error` set, like any other failed call.
|
|
91
|
+
- `tether.Halted` is raised when the run takes no more calls: a spent budget,
|
|
92
|
+
an unanswered ask, the kill switch, a provider failure. Anything else the
|
|
93
|
+
daemon refuses raises `tether.TetherError` with the gRPC status in `.code`.
|
|
94
|
+
- Arguments left unset fall back to `TETHER_POLICY`, `TETHER_DIR` and
|
|
95
|
+
`TETHER_SOCKET`, which `tether run -- python agent.py` sets.
|
|
96
|
+
|
|
97
|
+
## Develop
|
|
98
|
+
|
|
99
|
+
```
|
|
100
|
+
cd sdks/python
|
|
101
|
+
uv venv && uv pip install -e ".[dev]"
|
|
102
|
+
cargo build -p tetherd
|
|
103
|
+
.venv/bin/python -m pytest
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
The tests start a real daemon from `target/debug/tetherd` and use the
|
|
107
|
+
scripted model, so they need no API key. The gRPC stubs in
|
|
108
|
+
`src/tether/_proto` are generated and committed; regenerate them after a
|
|
109
|
+
change to `proto/tether.proto`:
|
|
110
|
+
|
|
111
|
+
```
|
|
112
|
+
uv run --no-project --with grpcio-tools sh scripts/gen_proto.sh
|
|
113
|
+
```
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
tether/__init__.py,sha256=8iSw-97nUd-C0U9YxavatVlwkrSg7dLeIaBVmDc4dmk,1223
|
|
2
|
+
tether/_run.py,sha256=U8UwrYiFSSSNKlUmwyJGfykqVmHhauvyy6LNh2iEHbc,12543
|
|
3
|
+
tether/_proto/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
4
|
+
tether/_proto/tether_pb2.py,sha256=9P4yiQxD5B6j5_QaFJSqXbqoY176Nt_-6crtyAqt_NU,5144
|
|
5
|
+
tether/_proto/tether_pb2_grpc.py,sha256=j5wJBtH_ovpCBwGc8M3UEr8nPHW4bUfrCRGWyDQ1qPM,13440
|
|
6
|
+
tether_agents-0.3.0.dist-info/METADATA,sha256=coAZ8QCySCH0BN30pudpVGhXn_FUE2R5oMZMFPQu6eQ,4472
|
|
7
|
+
tether_agents-0.3.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
8
|
+
tether_agents-0.3.0.dist-info/RECORD,,
|