@yahyahammad/venastine 0.1.0
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.
- package/.env.example +14 -0
- package/LICENSE +201 -0
- package/NOTICE +14 -0
- package/PRIVACY.md +66 -0
- package/README.md +878 -0
- package/SECURITY.md +88 -0
- package/THIRD_PARTY_NOTICES.md +100 -0
- package/agents/builtin/compactor.md +75 -0
- package/agents/builtin/explore.md +77 -0
- package/agents/builtin/grill-me.md +27 -0
- package/agents/builtin/initializer.md +94 -0
- package/agents/builtin/pipeline-reviewer.md +100 -0
- package/agents/builtin/plan.md +88 -0
- package/agents/builtin/review.md +74 -0
- package/agents/manager.py +195 -0
- package/agents/subagent_tool.py +215 -0
- package/agents/tui_commands.py +136 -0
- package/bin/venastine.mjs +382 -0
- package/config.py +1198 -0
- package/core/__init__.py +0 -0
- package/core/approval.py +115 -0
- package/core/client.py +1548 -0
- package/core/compaction.py +959 -0
- package/core/config_loader.py +1563 -0
- package/core/events.py +61 -0
- package/core/interaction.py +328 -0
- package/core/loop.py +1353 -0
- package/core/memory.py +370 -0
- package/core/model_windows.py +175 -0
- package/core/pipeline_models.py +176 -0
- package/core/reasoning/__init__.py +0 -0
- package/core/reasoning/authorization.py +130 -0
- package/core/reasoning/base.py +219 -0
- package/core/reasoning/confidence_scoring.py +468 -0
- package/core/reasoning/events.py +149 -0
- package/core/reasoning/json_retry.py +219 -0
- package/core/reasoning/orchestrator.py +1382 -0
- package/core/reasoning/output_writer.py +286 -0
- package/core/reasoning/payload_validation.py +398 -0
- package/core/reasoning/pipeline_storage.py +361 -0
- package/core/reasoning/review.py +615 -0
- package/core/reasoning/scholar.py +434 -0
- package/core/reasoning/source_corpus.py +327 -0
- package/core/reasoning/source_scoring.py +855 -0
- package/core/replay.py +167 -0
- package/core/session.py +153 -0
- package/core/workspace_trust.py +207 -0
- package/credentials.py +180 -0
- package/database.py +252 -0
- package/env_secrets.py +77 -0
- package/json_store.py +123 -0
- package/logging_setup.py +185 -0
- package/main.py +1959 -0
- package/mcp_client/__init__.py +15 -0
- package/mcp_client/client.py +499 -0
- package/mcp_client/config.py +379 -0
- package/mcp_client/registration.py +182 -0
- package/memories/manager.py +132 -0
- package/memories/tui_commands.py +232 -0
- package/package.json +73 -0
- package/project_init/config_files.py +278 -0
- package/project_init/doc_sets.py +330 -0
- package/project_init/generator.py +564 -0
- package/project_init/manifest.py +406 -0
- package/project_init/tui_commands.py +144 -0
- package/prompts/__init__.py +0 -0
- package/prompts/annotate.md +14 -0
- package/prompts/assumption_audit.md +27 -0
- package/prompts/claim_extraction.md +34 -0
- package/prompts/completeness.md +18 -0
- package/prompts/confidence_tiers.md +23 -0
- package/prompts/critic_pass.md +24 -0
- package/prompts/final_synthesis.md +13 -0
- package/prompts/initial_generation.md +14 -0
- package/prompts/preliminary_plan.md +23 -0
- package/prompts/revalidate.md +25 -0
- package/prompts/revise.md +15 -0
- package/prompts/source_grounding.md +66 -0
- package/prompts/system_prompts.py +262 -0
- package/prompts/universal_system_prompt +7 -0
- package/prompts/untrusted_content +1 -0
- package/providers.json.example +92 -0
- package/pyproject.toml +100 -0
- package/requirements.txt +72 -0
- package/safety/__init__.py +0 -0
- package/safety/policy_enforcement.py +682 -0
- package/security/__init__.py +0 -0
- package/security/capability.py +177 -0
- package/security/permissions.py +190 -0
- package/security/posture.py +302 -0
- package/security/protected_paths.py +309 -0
- package/security/sandbox.py +985 -0
- package/skills/builtin/crypto/cryptography-verification.md +66 -0
- package/skills/builtin/math/formal-specification.md +67 -0
- package/skills/builtin/math/numerical-methods.md +66 -0
- package/skills/builtin/math/proof-writing.md +61 -0
- package/skills/builtin/research/experiment-design.md +62 -0
- package/skills/builtin/research/literature-review.md +65 -0
- package/skills/builtin/research/reproducibility.md +55 -0
- package/skills/builtin/research/source-evaluation.md +70 -0
- package/skills/builtin/research/statistical-inference.md +63 -0
- package/skills/builtin/research/technical-writing.md +59 -0
- package/skills/builtin/security/cybersecurity-research.md +63 -0
- package/skills/builtin/software/code-review.md +61 -0
- package/skills/builtin/software/debugging.md +61 -0
- package/skills/builtin/software/test-design.md +67 -0
- package/skills/manager.py +138 -0
- package/skills/tui_commands.py +111 -0
- package/storage.py +1005 -0
- package/tools/base.py +305 -0
- package/tools/builtin/__init__.py +0 -0
- package/tools/builtin/_math_common.py +377 -0
- package/tools/builtin/_net_common.py +61 -0
- package/tools/builtin/arxiv.py +223 -0
- package/tools/builtin/ask_user.py +213 -0
- package/tools/builtin/discrete_math.py +134 -0
- package/tools/builtin/fetch_url.py +153 -0
- package/tools/builtin/file_ops.py +412 -0
- package/tools/builtin/geometry.py +148 -0
- package/tools/builtin/get_time.py +20 -0
- package/tools/builtin/linear_algebra.py +155 -0
- package/tools/builtin/load_skill.py +66 -0
- package/tools/builtin/logic.py +96 -0
- package/tools/builtin/pin.py +193 -0
- package/tools/builtin/probability_stats.py +228 -0
- package/tools/builtin/project_docs.py +405 -0
- package/tools/builtin/remember.py +158 -0
- package/tools/builtin/shell.py +461 -0
- package/tools/builtin/symbolic_math.py +119 -0
- package/tools/builtin/todo.py +147 -0
- package/tools/builtin/web_search.py +151 -0
- package/tools/context.py +136 -0
- package/tools/isolation.py +314 -0
- package/tools/registry.py +897 -0
- package/tui/app.py +3423 -0
- package/tui/app.tcss +458 -0
- package/tui/commands.py +61 -0
- package/tui/diffs.py +265 -0
- package/tui/preferences.py +182 -0
- package/tui/ravens.py +146 -0
- package/tui/screens.py +943 -0
- package/tui/themes.py +366 -0
- package/tui/widgets.py +1239 -0
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
"""
|
|
2
|
+
tools/builtin/_net_common.py
|
|
3
|
+
|
|
4
|
+
What the two network-backed search tools share. `_math_common.py`'s
|
|
5
|
+
precedent, one directory over: a private module the built-in tools import
|
|
6
|
+
from, never registered and never advertised.
|
|
7
|
+
|
|
8
|
+
TODAY THAT IS ONE THING: the in-process response cache. `web_search.py` and
|
|
9
|
+
`arxiv.py` each carried a `_cache_get` / `_cache_set` pair that was
|
|
10
|
+
identical apart from the type of the value being stored, plus a
|
|
11
|
+
`CACHE_TTL_S = 300` each, plus a bare dict each. Three copies of an expiry
|
|
12
|
+
rule is how one of them comes to be measured in minutes.
|
|
13
|
+
|
|
14
|
+
WHAT IS DELIBERATELY *NOT* SHARED. Each tool keeps its OWN instance, so the
|
|
15
|
+
two key spaces stay separate -- a `TTLCache` shared between them would let
|
|
16
|
+
an arXiv query and a web query collide on an equal key string, which is a
|
|
17
|
+
correctness bug rather than a tidiness one. Their `@field_validator`s
|
|
18
|
+
(`strip_keywords`, `strip_query`) are also left alone: they are three lines
|
|
19
|
+
each, they differ in the message the model is shown, and folding them into
|
|
20
|
+
a factory would make the params class harder to read to save two lines.
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
from __future__ import annotations
|
|
24
|
+
|
|
25
|
+
import time
|
|
26
|
+
from typing import Any, Optional
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class TTLCache:
|
|
30
|
+
"""A tiny time-boxed cache, keyed by whatever string a caller builds.
|
|
31
|
+
|
|
32
|
+
Expiry is checked on READ rather than swept: these caches hold a
|
|
33
|
+
handful of entries for the length of a research run, so a sweep would
|
|
34
|
+
be machinery for a problem neither tool has.
|
|
35
|
+
|
|
36
|
+
A stale entry is dropped as it is read, which is what makes a repeated
|
|
37
|
+
query after the TTL a real request again rather than a permanent miss
|
|
38
|
+
against a growing dict.
|
|
39
|
+
"""
|
|
40
|
+
|
|
41
|
+
def __init__(self, ttl_s: float) -> None:
|
|
42
|
+
self.ttl_s = ttl_s
|
|
43
|
+
self._entries: dict[str, tuple[float, Any]] = {}
|
|
44
|
+
|
|
45
|
+
def get(self, key: str) -> Optional[Any]:
|
|
46
|
+
entry = self._entries.get(key)
|
|
47
|
+
if not entry:
|
|
48
|
+
return None
|
|
49
|
+
stored_at, value = entry
|
|
50
|
+
if time.time() - stored_at > self.ttl_s:
|
|
51
|
+
self._entries.pop(key, None)
|
|
52
|
+
return None
|
|
53
|
+
return value
|
|
54
|
+
|
|
55
|
+
def set(self, key: str, value: Any) -> None:
|
|
56
|
+
self._entries[key] = (time.time(), value)
|
|
57
|
+
|
|
58
|
+
def clear(self) -> None:
|
|
59
|
+
"""Drop everything. For tests, which must not inherit a previous
|
|
60
|
+
test's answers -- the same reason conftest isolates the stores."""
|
|
61
|
+
self._entries.clear()
|
|
@@ -0,0 +1,223 @@
|
|
|
1
|
+
"""
|
|
2
|
+
tools/builtin/arxiv.py
|
|
3
|
+
|
|
4
|
+
Searches arXiv for academic papers by keyword and optional subject
|
|
5
|
+
category, using arXiv's public query API. No API key needed. Useful
|
|
6
|
+
alongside web_search/fetch_url for grounding claims in published research
|
|
7
|
+
during the source_grounding pass.
|
|
8
|
+
|
|
9
|
+
The arXiv API returns Atom 1.0 XML (not JSON) -- this file's job is
|
|
10
|
+
largely translating that into the same normalized result shape the other
|
|
11
|
+
tools use.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from __future__ import annotations
|
|
15
|
+
|
|
16
|
+
import logging
|
|
17
|
+
import xml.etree.ElementTree as ET
|
|
18
|
+
from typing import Optional
|
|
19
|
+
|
|
20
|
+
import httpx
|
|
21
|
+
from pydantic import BaseModel, Field, field_validator
|
|
22
|
+
|
|
23
|
+
from tools.builtin._net_common import TTLCache
|
|
24
|
+
|
|
25
|
+
logger = logging.getLogger(__name__)
|
|
26
|
+
|
|
27
|
+
# HTTPS, and it is load-bearing. arXiv 301-redirects the http:// form, and
|
|
28
|
+
# three things then combine into a hard failure that looks nothing like a
|
|
29
|
+
# redirect: httpx does NOT follow redirects by default (unlike requests),
|
|
30
|
+
# raise_for_status() only raises on >= 400 so a 301 sails through, and the
|
|
31
|
+
# redirect body is empty -- so ET.fromstring("") raises ParseError, the
|
|
32
|
+
# retry loop runs three identical attempts, and the tool reports "arXiv
|
|
33
|
+
# search failed after 3 attempts". Verified against the live API.
|
|
34
|
+
ARXIV_API_URL = "https://export.arxiv.org/api/query"
|
|
35
|
+
ATOM_NS = {"atom": "http://www.w3.org/2005/Atom"}
|
|
36
|
+
|
|
37
|
+
_VALID_SORT_BY = {"relevance", "lastUpdatedDate", "submittedDate"}
|
|
38
|
+
|
|
39
|
+
MAX_SUMMARY_CHARS = 600
|
|
40
|
+
REQUEST_TIMEOUT_S = 10.0
|
|
41
|
+
MAX_RETRIES = 2
|
|
42
|
+
CACHE_TTL_S = 300
|
|
43
|
+
|
|
44
|
+
# One instance per tool, never shared: an equal key string from an
|
|
45
|
+
# arXiv query and a web query would otherwise collide.
|
|
46
|
+
_cache = TTLCache(CACHE_TTL_S)
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
# ---- Schema exposed to the LLM -------------------------------------------
|
|
50
|
+
|
|
51
|
+
class ArxivSearchParams(BaseModel):
|
|
52
|
+
keywords: str = Field(..., description="Search keywords", min_length=1, max_length=400)
|
|
53
|
+
category: Optional[str] = Field(
|
|
54
|
+
None,
|
|
55
|
+
description=(
|
|
56
|
+
"Optional arXiv category code to restrict the search, e.g. "
|
|
57
|
+
"'cs.AI', 'cs.LG', 'physics.gen-ph', 'q-bio.NC'. Omit to search "
|
|
58
|
+
"all categories."
|
|
59
|
+
),
|
|
60
|
+
)
|
|
61
|
+
max_results: int = Field(5, ge=1, le=20, description="Number of results to return")
|
|
62
|
+
sort_by: str = Field(
|
|
63
|
+
"relevance",
|
|
64
|
+
description="How to sort results: 'relevance', 'lastUpdatedDate', or 'submittedDate'",
|
|
65
|
+
)
|
|
66
|
+
|
|
67
|
+
@field_validator("keywords")
|
|
68
|
+
@classmethod
|
|
69
|
+
def strip_keywords(cls, value: str) -> str:
|
|
70
|
+
value = value.strip()
|
|
71
|
+
if not value:
|
|
72
|
+
raise ValueError("keywords cannot be empty")
|
|
73
|
+
return value
|
|
74
|
+
|
|
75
|
+
@field_validator("sort_by")
|
|
76
|
+
@classmethod
|
|
77
|
+
def validate_sort_by(cls, value: str) -> str:
|
|
78
|
+
if value not in _VALID_SORT_BY:
|
|
79
|
+
raise ValueError(f"sort_by must be one of {_VALID_SORT_BY}")
|
|
80
|
+
return value
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
TOOL_SCHEMA = {
|
|
84
|
+
"name": "arxiv_search",
|
|
85
|
+
"description": (
|
|
86
|
+
"Search arXiv for academic papers by keyword and optional subject "
|
|
87
|
+
"category. Returns titles, authors, abstracts, publish dates, and "
|
|
88
|
+
"PDF links -- use this to ground claims in published research."
|
|
89
|
+
),
|
|
90
|
+
"input_schema": ArxivSearchParams.model_json_schema(),
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
class ArxivSearchError(Exception):
|
|
95
|
+
"""No longer raised by this module -- exhausted retries return an
|
|
96
|
+
error dict instead, so a transient network failure cannot fail a
|
|
97
|
+
ten-pass research run. Kept because it is part of this module's
|
|
98
|
+
public surface and something outside the repo may catch it."""
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
# ---- Query construction -----------------------------------------------------
|
|
102
|
+
|
|
103
|
+
def _build_search_query(keywords: str, category: Optional[str]) -> str:
|
|
104
|
+
"""
|
|
105
|
+
arXiv's query syntax uses field prefixes (ti:, abs:, au:, cat:, all:)
|
|
106
|
+
combined with AND/OR/ANDNOT. `all:` searches title, abstract, and
|
|
107
|
+
author. httpx handles URL-encoding the spaces/quotes once this string
|
|
108
|
+
is passed as a params value, so no manual encoding is needed here.
|
|
109
|
+
"""
|
|
110
|
+
if category:
|
|
111
|
+
return f"cat:{category} AND all:{keywords}"
|
|
112
|
+
return f"all:{keywords}"
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
# ---- Provider call ----------------------------------------------------------
|
|
116
|
+
|
|
117
|
+
def _call_arxiv_api(search_query: str, max_results: int, sort_by: str) -> str:
|
|
118
|
+
response = httpx.get(
|
|
119
|
+
ARXIV_API_URL,
|
|
120
|
+
params={
|
|
121
|
+
"search_query": search_query,
|
|
122
|
+
"start": 0,
|
|
123
|
+
"max_results": max_results,
|
|
124
|
+
"sortBy": sort_by,
|
|
125
|
+
"sortOrder": "descending",
|
|
126
|
+
},
|
|
127
|
+
headers={"User-Agent": "agent-harness-arxiv-tool/1.0 (research pipeline)"},
|
|
128
|
+
timeout=REQUEST_TIMEOUT_S,
|
|
129
|
+
# Belt and braces beside the https:// above. If arXiv moves the
|
|
130
|
+
# endpoint again, following the redirect keeps this working
|
|
131
|
+
# instead of failing as an unparseable empty body.
|
|
132
|
+
follow_redirects=True,
|
|
133
|
+
)
|
|
134
|
+
response.raise_for_status()
|
|
135
|
+
return response.text # raw Atom XML
|
|
136
|
+
|
|
137
|
+
|
|
138
|
+
# ---- Atom XML parsing --------------------------------------------------
|
|
139
|
+
|
|
140
|
+
def _parse_atom_feed(xml_text: str) -> list[dict]:
|
|
141
|
+
root = ET.fromstring(xml_text)
|
|
142
|
+
entries = root.findall("atom:entry", ATOM_NS)
|
|
143
|
+
|
|
144
|
+
results = []
|
|
145
|
+
for entry in entries:
|
|
146
|
+
raw_id = entry.find("atom:id", ATOM_NS).text.strip()
|
|
147
|
+
arxiv_id = raw_id.split("/abs/")[-1] if "/abs/" in raw_id else raw_id
|
|
148
|
+
|
|
149
|
+
title = entry.find("atom:title", ATOM_NS).text.strip().replace("\n", " ")
|
|
150
|
+
summary_el = entry.find("atom:summary", ATOM_NS)
|
|
151
|
+
summary = (summary_el.text or "").strip().replace("\n", " ")[:MAX_SUMMARY_CHARS]
|
|
152
|
+
|
|
153
|
+
published_el = entry.find("atom:published", ATOM_NS)
|
|
154
|
+
published = published_el.text[:10] if published_el is not None else None
|
|
155
|
+
|
|
156
|
+
authors = [
|
|
157
|
+
a.find("atom:name", ATOM_NS).text
|
|
158
|
+
for a in entry.findall("atom:author", ATOM_NS)
|
|
159
|
+
]
|
|
160
|
+
categories = [c.get("term") for c in entry.findall("atom:category", ATOM_NS)]
|
|
161
|
+
|
|
162
|
+
pdf_url = None
|
|
163
|
+
for link in entry.findall("atom:link", ATOM_NS):
|
|
164
|
+
if link.get("title") == "pdf":
|
|
165
|
+
pdf_url = link.get("href")
|
|
166
|
+
|
|
167
|
+
results.append({
|
|
168
|
+
"arxiv_id": arxiv_id,
|
|
169
|
+
"title": title,
|
|
170
|
+
"authors": authors,
|
|
171
|
+
"summary": summary,
|
|
172
|
+
"published": published,
|
|
173
|
+
"categories": categories,
|
|
174
|
+
"pdf_url": pdf_url,
|
|
175
|
+
})
|
|
176
|
+
|
|
177
|
+
return results
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
# ---- Entry point called by the tool dispatcher -----------------------------
|
|
181
|
+
|
|
182
|
+
def run(params: dict) -> dict:
|
|
183
|
+
parsed = ArxivSearchParams(**params)
|
|
184
|
+
cache_key = f"{parsed.keywords}|{parsed.category}|{parsed.max_results}|{parsed.sort_by}"
|
|
185
|
+
|
|
186
|
+
results = _cache.get(cache_key)
|
|
187
|
+
if results is not None:
|
|
188
|
+
logger.info("arxiv_search cache hit for %r", parsed.keywords)
|
|
189
|
+
else:
|
|
190
|
+
search_query = _build_search_query(parsed.keywords, parsed.category)
|
|
191
|
+
last_exc: Optional[Exception] = None
|
|
192
|
+
results = []
|
|
193
|
+
for attempt in range(MAX_RETRIES + 1):
|
|
194
|
+
try:
|
|
195
|
+
xml_text = _call_arxiv_api(search_query, parsed.max_results, parsed.sort_by)
|
|
196
|
+
results = _parse_atom_feed(xml_text)
|
|
197
|
+
_cache.set(cache_key, results)
|
|
198
|
+
break
|
|
199
|
+
except (httpx.HTTPError, ET.ParseError) as e:
|
|
200
|
+
last_exc = e
|
|
201
|
+
logger.warning(
|
|
202
|
+
"arxiv_search attempt %s/%s failed for %r: %s",
|
|
203
|
+
attempt + 1, MAX_RETRIES + 1, parsed.keywords, e)
|
|
204
|
+
else:
|
|
205
|
+
# RETURNED, not raised. A search tool that cannot reach its
|
|
206
|
+
# provider is a result the model can work around -- try
|
|
207
|
+
# web_search, or say the claim could not be grounded. Raising
|
|
208
|
+
# made one transient network failure, in one pass, fail an
|
|
209
|
+
# entire ten-pass research run; fetch_url has always returned
|
|
210
|
+
# an error dict here and arxiv_search was the outlier.
|
|
211
|
+
#
|
|
212
|
+
# dispatch() now contains a raise from any tool as well, so
|
|
213
|
+
# this is the message rather than the mechanism: the model
|
|
214
|
+
# gets something specific instead of a generic wrapper.
|
|
215
|
+
return {
|
|
216
|
+
"error": f"arXiv search failed after {MAX_RETRIES + 1} "
|
|
217
|
+
f"attempts: {last_exc}"
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
if not results:
|
|
221
|
+
return {"results": [], "result_count": 0, "message": "No papers found."}
|
|
222
|
+
|
|
223
|
+
return {"results": results, "result_count": len(results)}
|
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
"""
|
|
2
|
+
tools/builtin/ask_user.py
|
|
3
|
+
|
|
4
|
+
ROADMAP_v2 §23 slice 2: the question tool. "Up to 4 options, multi-select, a
|
|
5
|
+
write-your-own answer, and a 'chat about this' escape that returns control to
|
|
6
|
+
the conversation instead of forcing a choice."
|
|
7
|
+
|
|
8
|
+
IT ASKS THROUGH THE INJECTED CHANNEL, NOT THROUGH THE APPROVAL BRIDGE. The
|
|
9
|
+
loop's `_obtain_approval` fires only under `if needs_approval:`, builds a
|
|
10
|
+
payload of {"tool_name", "params"}, and coerces the answer to (bool, grant) --
|
|
11
|
+
a free-text or multi-select answer has nowhere to go in it. It does not need
|
|
12
|
+
one: `response_channel` is already an injectable parameter, handed to every
|
|
13
|
+
handler that names it on BOTH dispatch branches, which is what
|
|
14
|
+
tools/registry.py's `_INJECTABLE_PARAMS` comment anticipated -- "generalised
|
|
15
|
+
so §23's response-channel tools add a third injectable name without reopening
|
|
16
|
+
dispatch()". So core/loop.py is untouched by this tool.
|
|
17
|
+
|
|
18
|
+
UNGATED, DELIBERATELY (J12). Requiring approval to ask a question would mean
|
|
19
|
+
approving a prompt in order to be shown a prompt -- and worse, §13 does not
|
|
20
|
+
merely deny a gated tool where nothing can ask, it stops ADVERTISING it. A
|
|
21
|
+
gated question tool would be invisible in every headless run rather than
|
|
22
|
+
denied with a reason, and §23 AC2 wants the opposite: the model must see the tool,
|
|
23
|
+
call it, and receive "there is nobody to ask" as something it can work around.
|
|
24
|
+
Same shape as `pin`'s ungating (D26), for the same reason.
|
|
25
|
+
|
|
26
|
+
NO CHANNEL MEANS DENIED, AND THE DENIAL EXPLAINS ITSELF (§23 AC2). An unattended
|
|
27
|
+
ten-pass pipeline is exactly where a blocking prompt nobody will answer turns
|
|
28
|
+
into a hang, and where a question injected by fetched web content would be
|
|
29
|
+
least noticed. An attended run carries a channel and can ask -- that is §25's
|
|
30
|
+
amendment, and it is why the condition tested here is "is there a channel"
|
|
31
|
+
rather than "is this the pipeline".
|
|
32
|
+
"""
|
|
33
|
+
|
|
34
|
+
import logging
|
|
35
|
+
|
|
36
|
+
from core import interaction
|
|
37
|
+
|
|
38
|
+
logger = logging.getLogger(__name__)
|
|
39
|
+
|
|
40
|
+
# The spec's cap, enforced rather than advisory. See run() for why a fifth
|
|
41
|
+
# option is an error and not a truncation.
|
|
42
|
+
MAX_OPTIONS = 4
|
|
43
|
+
|
|
44
|
+
#: Longest option the modal can show whole (batch 49). QuestionScreen is a
|
|
45
|
+
#: fixed 66 columns and an option button 58 of them, so 100 characters is
|
|
46
|
+
#: two wrapped lines for every shape measured -- prose, twenty-character
|
|
47
|
+
#: words, and an unbroken run -- and 105 is three for two of them. It is a
|
|
48
|
+
#: BUDGET, not a guess: the options region scrolls, so exceeding it costs
|
|
49
|
+
#: legibility rather than correctness, and the number is re-derivable by
|
|
50
|
+
#: the test that measures the drawn rows rather than trusting this
|
|
51
|
+
#: comment.
|
|
52
|
+
MAX_OPTION_CHARS = 100
|
|
53
|
+
|
|
54
|
+
TOOL_SCHEMA = {
|
|
55
|
+
"name": "ask_user",
|
|
56
|
+
"description": (
|
|
57
|
+
"Ask the user a question and wait for their answer. Use this when a "
|
|
58
|
+
"decision is genuinely theirs to make and getting it wrong would "
|
|
59
|
+
"waste work -- an ambiguous requirement, a choice between "
|
|
60
|
+
"approaches with different tradeoffs, a missing fact only they "
|
|
61
|
+
"have. Do NOT use it for things you can determine yourself, or to "
|
|
62
|
+
"confirm work you have already been asked to do. The user can pick "
|
|
63
|
+
"one or more of your options, write their own answer, or ask to "
|
|
64
|
+
"discuss it instead of choosing."
|
|
65
|
+
),
|
|
66
|
+
"input_schema": {
|
|
67
|
+
"type": "object",
|
|
68
|
+
"properties": {
|
|
69
|
+
"question": {
|
|
70
|
+
"type": "string",
|
|
71
|
+
"description": "The question, in one or two sentences. State "
|
|
72
|
+
"what you need and why it changes what you "
|
|
73
|
+
"will do.",
|
|
74
|
+
},
|
|
75
|
+
"options": {
|
|
76
|
+
"type": "array",
|
|
77
|
+
"items": {"type": "string"},
|
|
78
|
+
"description": f"Up to {MAX_OPTIONS} concrete answers to "
|
|
79
|
+
f"choose from. Optional -- omit it to ask an "
|
|
80
|
+
f"open question. Each must be at most "
|
|
81
|
+
f"{MAX_OPTION_CHARS} characters, so it can be "
|
|
82
|
+
f"shown whole -- put the reasoning in the "
|
|
83
|
+
f"question, not in the options.",
|
|
84
|
+
},
|
|
85
|
+
"multi_select": {
|
|
86
|
+
"type": "boolean",
|
|
87
|
+
"description": "True if several options can be chosen "
|
|
88
|
+
"together. Defaults to false.",
|
|
89
|
+
},
|
|
90
|
+
"allow_text": {
|
|
91
|
+
"type": "boolean",
|
|
92
|
+
"description": "Whether the user may write their own answer "
|
|
93
|
+
"instead of picking. Defaults to true.",
|
|
94
|
+
},
|
|
95
|
+
},
|
|
96
|
+
"required": ["question"],
|
|
97
|
+
},
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def run(params: dict, response_channel=None) -> dict:
|
|
102
|
+
# params.get throughout, never params[]: no provider validates tool
|
|
103
|
+
# inputs against the schema, and a bare KeyError escapes the loop's
|
|
104
|
+
# ToolCallDenied handler and takes down the whole turn. pin.py's rule.
|
|
105
|
+
question = params.get("question")
|
|
106
|
+
if not question or not isinstance(question, str):
|
|
107
|
+
return {"error": "ask_user requires a 'question' string."}
|
|
108
|
+
|
|
109
|
+
options = params.get("options") or []
|
|
110
|
+
if not isinstance(options, (list, tuple)):
|
|
111
|
+
return {"error": "ask_user requires 'options' to be a list of strings."}
|
|
112
|
+
options = [str(o) for o in options]
|
|
113
|
+
|
|
114
|
+
if len(options) > MAX_OPTIONS:
|
|
115
|
+
# AN ERROR, NOT A TRUNCATION. Silently dropping the fifth option
|
|
116
|
+
# would show the user a different question from the one the model
|
|
117
|
+
# asked, and the model would then read the answer as a response to
|
|
118
|
+
# the full list. M15's rule -- never silently drop something
|
|
119
|
+
# somebody named -- with the model in the naming role. An error it
|
|
120
|
+
# can correct costs one step; a mis-answered question costs the
|
|
121
|
+
# decision.
|
|
122
|
+
return {
|
|
123
|
+
"error": f"ask_user allows at most {MAX_OPTIONS} options; "
|
|
124
|
+
f"{len(options)} were given. Ask a narrower question, "
|
|
125
|
+
f"or drop the options and ask it openly.",
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
too_long = [o for o in options if len(o) > MAX_OPTION_CHARS]
|
|
129
|
+
if too_long:
|
|
130
|
+
# AN ERROR, NOT A TRUNCATION, for the reason directly above: an
|
|
131
|
+
# option shortened here is not the option the model offered, and
|
|
132
|
+
# the answer would come back as though it were. The modal used to
|
|
133
|
+
# truncate this way by accident -- an option wider than the dialog
|
|
134
|
+
# was CUT at its edge, so a user chose between two options whose
|
|
135
|
+
# visible halves were identical -- which is the failure this
|
|
136
|
+
# refusal exists to make impossible rather than merely unlikely.
|
|
137
|
+
longest = max(too_long, key=len)
|
|
138
|
+
return {
|
|
139
|
+
"error": f"ask_user allows at most {MAX_OPTION_CHARS} characters "
|
|
140
|
+
f"per option so it can be read whole; one is "
|
|
141
|
+
f"{len(longest)}. Shorten it to the choice itself and "
|
|
142
|
+
f"put the reasoning in the question: "
|
|
143
|
+
f"{longest[:60]!r}...",
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
if not options and params.get("allow_text", True) is False:
|
|
147
|
+
# #114, same family as the two refusals above: a question with no
|
|
148
|
+
# options and no text box renders as a modal whose only button is
|
|
149
|
+
# "Discuss instead", so a defer means "that was my only button"
|
|
150
|
+
# rather than "let's talk about it" -- collapsing exactly the
|
|
151
|
+
# distinction QuestionScreen's escape/defer pair exists to keep.
|
|
152
|
+
return {
|
|
153
|
+
"error": "ask_user needs something to answer with: give "
|
|
154
|
+
"options, or leave allow_text true so the user can "
|
|
155
|
+
"write a reply.",
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
if response_channel is None:
|
|
159
|
+
# §23 AC2. Not an exception: dispatch would convert one to an error dict
|
|
160
|
+
# anyway, and this way the message is written for the reader who
|
|
161
|
+
# needs it -- a model mid-run that must now decide something itself.
|
|
162
|
+
return {
|
|
163
|
+
"error": "ask_user cannot reach anyone in this run -- there is "
|
|
164
|
+
"nobody to answer. Decide it yourself, state the "
|
|
165
|
+
"assumption you are proceeding on, and carry on.",
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
answer = interaction.ask(response_channel, interaction.Request(
|
|
169
|
+
kind=interaction.QUESTION,
|
|
170
|
+
payload={
|
|
171
|
+
"question": question,
|
|
172
|
+
"options": options,
|
|
173
|
+
"multi_select": bool(params.get("multi_select")),
|
|
174
|
+
# Defaults TRUE: the spec lists a write-your-own answer as one of
|
|
175
|
+
# the four affordances, so absence of the key is not absence of
|
|
176
|
+
# the affordance.
|
|
177
|
+
"allow_text": params.get("allow_text", True) is not False,
|
|
178
|
+
},
|
|
179
|
+
))
|
|
180
|
+
|
|
181
|
+
if answer is None:
|
|
182
|
+
# Nobody answered -- dismissed, timed out, or a shell returning
|
|
183
|
+
# something decode could not read. Distinct from a deferral below,
|
|
184
|
+
# and reported as such: "they declined to answer" and "they want to
|
|
185
|
+
# discuss it" call for different next moves.
|
|
186
|
+
return {
|
|
187
|
+
"error": "The user did not answer the question. Proceed on your "
|
|
188
|
+
"best judgement and say which assumption you made.",
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
if answer.get("defer"):
|
|
192
|
+
# The spec's escape, "returns control to the conversation instead of
|
|
193
|
+
# forcing a choice". A result rather than any change of control
|
|
194
|
+
# flow: the loop has one shape, and a tool that could abort a turn
|
|
195
|
+
# would be a second one. The model simply talks next.
|
|
196
|
+
return {
|
|
197
|
+
"result": "The user would rather discuss this than pick an "
|
|
198
|
+
"answer. Raise it in conversation -- do not call "
|
|
199
|
+
"ask_user again for the same question.",
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
chosen, text = answer.get("options") or [], answer.get("text") or ""
|
|
203
|
+
if not chosen and not text:
|
|
204
|
+
# A blank submission. They were present and said nothing, which is
|
|
205
|
+
# not the same as never being asked -- so this is not the no-channel
|
|
206
|
+
# error, and the wording does not tell the model to assume anything.
|
|
207
|
+
return {
|
|
208
|
+
"result": "The user answered without choosing an option or "
|
|
209
|
+
"writing anything. Ask again more specifically, or "
|
|
210
|
+
"raise it in conversation.",
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
return {"result": {"chosen": chosen, "text": text}}
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
"""
|
|
2
|
+
tools/builtin/discrete_math.py
|
|
3
|
+
|
|
4
|
+
Number theory and combinatorics: gcd/lcm, primality, factorization,
|
|
5
|
+
factorial, permutations, combinations, and modular arithmetic.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
from typing import Literal, Optional
|
|
11
|
+
|
|
12
|
+
import sympy
|
|
13
|
+
from pydantic import BaseModel, Field
|
|
14
|
+
|
|
15
|
+
_OPERATIONS = Literal[
|
|
16
|
+
"gcd", "lcm", "is_prime", "prime_factors", "next_prime",
|
|
17
|
+
"factorial", "permutations", "combinations",
|
|
18
|
+
"modular_exponent", "mod_inverse",
|
|
19
|
+
]
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
class DiscreteMathParams(BaseModel):
|
|
23
|
+
operation: _OPERATIONS = Field(..., description="Which operation to perform")
|
|
24
|
+
a: Optional[int] = Field(None, description="First integer, for gcd/lcm")
|
|
25
|
+
b: Optional[int] = Field(None, description="Second integer, for gcd/lcm")
|
|
26
|
+
n: Optional[int] = Field(None, description="n, for is_prime/prime_factors/next_prime/factorial/permutations/combinations")
|
|
27
|
+
r: Optional[int] = Field(None, description="r, for permutations (nPr) / combinations (nCr)")
|
|
28
|
+
base: Optional[int] = Field(None, description="base, for modular_exponent/mod_inverse")
|
|
29
|
+
exponent: Optional[int] = Field(None, description="exponent, for modular_exponent")
|
|
30
|
+
modulus: Optional[int] = Field(None, description="modulus, for modular_exponent/mod_inverse")
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
TOOL_SCHEMA = {
|
|
34
|
+
"name": "discrete_math",
|
|
35
|
+
"description": (
|
|
36
|
+
"Number theory and combinatorics: gcd, lcm, primality testing, "
|
|
37
|
+
"prime factorization, next prime, factorial, permutations (nPr), "
|
|
38
|
+
"combinations (nCr), modular exponentiation, and modular inverse."
|
|
39
|
+
),
|
|
40
|
+
"input_schema": DiscreteMathParams.model_json_schema(),
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def run(params: dict) -> dict:
|
|
45
|
+
parsed = DiscreteMathParams(**params)
|
|
46
|
+
|
|
47
|
+
try:
|
|
48
|
+
op = parsed.operation
|
|
49
|
+
|
|
50
|
+
if op == "gcd":
|
|
51
|
+
if parsed.a is None or parsed.b is None:
|
|
52
|
+
return {"error": "gcd requires 'a' and 'b' (both integers)."}
|
|
53
|
+
result = sympy.gcd(parsed.a, parsed.b)
|
|
54
|
+
elif op == "lcm":
|
|
55
|
+
if parsed.a is None or parsed.b is None:
|
|
56
|
+
return {"error": "lcm requires 'a' and 'b' (both integers)."}
|
|
57
|
+
result = sympy.lcm(parsed.a, parsed.b)
|
|
58
|
+
elif op == "is_prime":
|
|
59
|
+
if parsed.n is None:
|
|
60
|
+
return {"error": "is_prime requires 'n' (integer)."}
|
|
61
|
+
result = sympy.isprime(parsed.n)
|
|
62
|
+
elif op == "prime_factors":
|
|
63
|
+
if parsed.n is None:
|
|
64
|
+
return {"error": "prime_factors requires 'n' (integer)."}
|
|
65
|
+
result = sympy.factorint(parsed.n) # {prime: exponent}
|
|
66
|
+
elif op == "next_prime":
|
|
67
|
+
if parsed.n is None:
|
|
68
|
+
return {"error": "next_prime requires 'n' (integer)."}
|
|
69
|
+
result = sympy.nextprime(parsed.n)
|
|
70
|
+
elif op == "factorial":
|
|
71
|
+
if parsed.n is None:
|
|
72
|
+
return {"error": "factorial requires 'n' (integer)."}
|
|
73
|
+
result = sympy.factorial(parsed.n)
|
|
74
|
+
elif op == "permutations":
|
|
75
|
+
# nPr = n! / (n-r)! -- computed directly rather than relying
|
|
76
|
+
# on a less-common sympy function name.
|
|
77
|
+
if parsed.n is None or parsed.r is None:
|
|
78
|
+
return {"error": "permutations requires 'n' and 'r' (integers)."}
|
|
79
|
+
result = sympy.factorial(parsed.n) / sympy.factorial(parsed.n - parsed.r)
|
|
80
|
+
elif op == "combinations":
|
|
81
|
+
if parsed.n is None or parsed.r is None:
|
|
82
|
+
return {"error": "combinations requires 'n' and 'r' (integers)."}
|
|
83
|
+
result = sympy.binomial(parsed.n, parsed.r)
|
|
84
|
+
elif op == "modular_exponent":
|
|
85
|
+
# H5. `pow(b, e, None)` is PLAIN exponentiation, and modulus
|
|
86
|
+
# is Optional -- so omitting one field silently turned this
|
|
87
|
+
# into a different operation with a different complexity
|
|
88
|
+
# class. Measured: exponent=10**9 with a modulus is 0.000s;
|
|
89
|
+
# without one it is 3.3s and a 125 MB integer, and the model
|
|
90
|
+
# chooses the arguments.
|
|
91
|
+
#
|
|
92
|
+
# An ERROR naming the field, not a silent plain power and not
|
|
93
|
+
# a separate `power` operation -- the second would advertise
|
|
94
|
+
# the unbounded path rather than close it. The tool's name is
|
|
95
|
+
# its contract, and H2's clock is a backstop for the runaway
|
|
96
|
+
# rather than a licence to keep offering it.
|
|
97
|
+
if parsed.base is None or parsed.exponent is None:
|
|
98
|
+
return {"error": "modular_exponent requires 'base', 'exponent' and 'modulus' (all integers)."}
|
|
99
|
+
if parsed.modulus is None:
|
|
100
|
+
return {"error": "modular_exponent requires a modulus. Without one this is plain exponentiation, which can produce a number too large to compute or return. Supply modulus, or ask for a smaller exponent."}
|
|
101
|
+
if parsed.modulus == 0:
|
|
102
|
+
return {"error": "modular_exponent requires a non-zero modulus (modulus cannot be 0)."}
|
|
103
|
+
result = pow(parsed.base, parsed.exponent, parsed.modulus)
|
|
104
|
+
elif op == "mod_inverse":
|
|
105
|
+
if parsed.base is None or parsed.modulus is None:
|
|
106
|
+
return {"error": "mod_inverse requires 'base' and 'modulus' (integers)."}
|
|
107
|
+
if parsed.modulus == 0:
|
|
108
|
+
return {"error": "mod_inverse requires a non-zero modulus (modulus cannot be 0)."}
|
|
109
|
+
result = sympy.mod_inverse(parsed.base, parsed.modulus)
|
|
110
|
+
else:
|
|
111
|
+
return {"error": f"Unknown operation: {op}"}
|
|
112
|
+
|
|
113
|
+
except Exception as e:
|
|
114
|
+
return {"error": f"Computation failed: {e}"}
|
|
115
|
+
|
|
116
|
+
# H6. The str() below is the SECOND place this function can fail, and
|
|
117
|
+
# it used to sit outside the try above -- so a correct answer that
|
|
118
|
+
# was merely too large to print left the handler as a bare
|
|
119
|
+
# ValueError, reached dispatch's containment, and was logged with a
|
|
120
|
+
# full traceback as though it were a bug in the harness. CPython caps
|
|
121
|
+
# int->str at 4300 digits, so `factorial n=100000` reaches this on
|
|
122
|
+
# ordinary input.
|
|
123
|
+
#
|
|
124
|
+
# Contained here rather than left to dispatch because dispatch's
|
|
125
|
+
# backstop exists for real bugs, and filling it with routine outcomes
|
|
126
|
+
# is how a real one stops being noticed. The message also has to tell
|
|
127
|
+
# the model something it can act on; the generic wrapper does not.
|
|
128
|
+
try:
|
|
129
|
+
if isinstance(result, dict):
|
|
130
|
+
return {"result": {str(k): v for k, v in result.items()},
|
|
131
|
+
"operation": op}
|
|
132
|
+
return {"result": str(result), "operation": op}
|
|
133
|
+
except ValueError as e:
|
|
134
|
+
return {"error": f"The {op} result was computed but is too large to return ({e}). Ask for the same operation with smaller inputs."}
|