;
; tool-exploration-real.scm
;
; Can the agent learn tools "in its head" or does it need actual shell access?
; Answer: Both have value, but GROUNDED learning requires actual execution.
;
(use-modules (srfi srfi-1))
(use-modules (ice-9 format))
(display "═══════════════════════════════════════════════════════════════════\n")
(display " TOOL LEARNING: In-Head vs Actual Execution \n")
(display "═══════════════════════════════════════════════════════════════════\n\n")
;; ═══════════════════════════════════════════════════════════════════
;; APPROACH 1: LEARNING FROM TEXT ("In the head")
;; ═══════════════════════════════════════════════════════════════════
(display "═══════════════════════════════════════════════════════════════════\n")
(display "APPROACH 1: Learning Tools From Text Descriptions\n")
(display "─────────────────────────────────────────────────────────────────\n\n")
(display " If the corpus contains text ABOUT tools:\n\n")
(define tool-descriptions '(
"To list files in a directory, use the ls command."
"The cat command displays the contents of a file."
"Use grep to search for patterns in files."
"The curl command downloads content from URLs."
"To search the web, type your query into Google."
))
(for-each (lambda (s) (format #t " '~a'\n" s)) tool-descriptions)
(newline)
(display " The agent can learn:\n")
(display " - 'ls' co-occurs with 'list', 'files', 'directory'\n")
(display " - 'cat' co-occurs with 'displays', 'contents', 'file'\n")
(display " - 'grep' co-occurs with 'search', 'patterns'\n")
(display " - 'curl' co-occurs with 'downloads', 'URLs'\n\n")
(display " From PMI, it might cluster:\n")
(display " CLUSTER-FILE-OPS: {ls, cat, grep} (co-occur with 'file')\n")
(display " CLUSTER-NETWORK: {curl} (co-occurs with 'URL', 'download')\n\n")
(display " PROBLEM: This is UNGROUNDED knowledge!\n\n")
(display " ┌─────────────────────────────────────────────────────────────┐\n")
(display " │ The agent has learned: │\n")
(display " │ 'ls' is associated with 'list files' │\n")
(display " │ │\n")
(display " │ But it does NOT know: │\n")
(display " │ - What 'ls' actually DOES when executed │\n")
(display " │ - Whether these descriptions are ACCURATE │\n")
(display " │ - What the OUTPUT looks like │\n")
(display " │ - What ERRORS might occur │\n")
(display " │ - The exact SYNTAX required │\n")
(display " │ │\n")
(display " │ This is like reading a cookbook vs actually cooking. │\n")
(display " └─────────────────────────────────────────────────────────────┘\n\n")
;; ═══════════════════════════════════════════════════════════════════
;; APPROACH 2: ACTUAL SHELL EXPLORATION
;; ═══════════════════════════════════════════════════════════════════
(display "═══════════════════════════════════════════════════════════════════\n")
(display "APPROACH 2: Actual Shell Exploration (Grounded Learning)\n")
(display "─────────────────────────────────────────────────────────────────\n\n")
(display " The agent has access to a shell. It can:\n")
(display " - Send commands (strings)\n")
(display " - Observe responses (strings)\n")
(display " - Measure outcomes (success/error, information content)\n\n")
(display " Let's trace ACTUAL exploration:\n\n")
(display "─────────────────────────────────────────────────────────────────\n")
(display "EXPLORATION SESSION 1: Random/Guided Discovery\n")
(display "─────────────────────────────────────────────────────────────────\n\n")
;; Simulate actual shell interaction
(define exploration-log '(
;; (action response reward notes)
("help"
"GNU bash, version 5.1.16... Type 'help name' for info about builtin..."
0.5
"Got text back - some commands listed")
("asdfqwer"
"bash: asdfqwer: command not found"
-0.2
"Error - not a valid command")
("ls"
"Desktop Documents Downloads file.txt test.py"
0.8
"Got structured output - looks like file names")
("ls --help"
"Usage: ls [OPTION]... [FILE]... List directory contents..."
0.9
"Got help text - shows options and arguments")
("cat"
"^C"
-0.1
"Hung waiting for input - needs argument")
("cat file.txt"
"Hello world. This is a test file with some content."
0.9
"Got file contents - 'cat' shows inside of files")
("cat nonexistent.txt"
"cat: nonexistent.txt: No such file or directory"
0.3
"Error but informative - file must exist")
("echo hello"
"hello"
0.7
"Echoes back the argument")
("echo bank river money"
"bank river money"
0.7
"Echoes multiple words")
))
(for-each
(lambda (entry)
(let ((action (car entry))
(response (cadr entry))
(reward (caddr entry))
(notes (cadddr entry)))
(format #t " ACTION: ~a\n" action)
(format #t " RESPONSE: ~a\n"
(if (> (string-length response) 60)
(string-append (substring response 0 57) "...")
response))
(format #t " REWARD: ~,1f (~a)\n\n" reward notes)))
(take exploration-log 5))
(display " ... [more exploration] ...\n\n")
;; ═══════════════════════════════════════════════════════════════════
;; WHAT THE AGENT LEARNS FROM ACTUAL EXECUTION
;; ═══════════════════════════════════════════════════════════════════
(display "═══════════════════════════════════════════════════════════════════\n")
(display "WHAT THE AGENT LEARNS FROM ACTUAL EXECUTION\n")
(display "─────────────────────────────────────────────────────────────────\n\n")
(display " Layer 1: Action-Response Co-occurrences\n")
(display " ─────────────────────────────────────────\n\n")
(display " PMI(ls, 'Desktop Documents...') = HIGH\n")
(display " PMI(ls, file-listing-pattern) = HIGH\n")
(display " PMI(cat, file-contents) = HIGH\n")
(display " PMI(cat, 'No such file') = MEDIUM (error case)\n")
(display " PMI(echo, exact-input-returned) = VERY HIGH\n")
(display " PMI(random-string, 'command not found') = HIGH\n\n")
(display " Layer 2: Discovered Patterns\n")
(display " ────────────────────────────\n\n")
(display " PATTERN 1: Commands that need arguments\n")
(display " cat FILE → contents of FILE\n")
(display " cat (no arg) → hangs/waits\n")
(display " → 'cat' REQUIRES an argument\n\n")
(display " PATTERN 2: Commands that work alone\n")
(display " ls → list of current directory\n")
(display " ls PATH → list of PATH\n")
(display " → 'ls' has OPTIONAL argument\n\n")
(display " PATTERN 3: Error patterns\n")
(display " 'command not found' → invalid command\n")
(display " 'No such file' → valid command, bad argument\n")
(display " → Can distinguish command errors from argument errors\n\n")
(display " PATTERN 4: Help discovery\n")
(display " COMMAND --help → usage information\n")
(display " man COMMAND → detailed manual\n")
(display " → Can learn about commands before using them\n\n")
;; ═══════════════════════════════════════════════════════════════════
;; GROUNDED VS UNGROUNDED KNOWLEDGE
;; ═══════════════════════════════════════════════════════════════════
(display "═══════════════════════════════════════════════════════════════════\n")
(display "GROUNDED VS UNGROUNDED TOOL KNOWLEDGE\n")
(display "─────────────────────────────────────────────────────────────────\n\n")
(display " ┌─────────────────────────────────────────────────────────────┐\n")
(display " │ UNGROUNDED (from text): │\n")
(display " │ 'ls lists files' │\n")
(display " │ Confidence: LOW (could be wrong, outdated, fictional) │\n")
(display " │ │\n")
(display " │ GROUNDED (from execution): │\n")
(display " │ ls → 'Desktop Documents Downloads file.txt test.py' │\n")
(display " │ Confidence: HIGH (observed directly) │\n")
(display " │ Also learned: output format, current directory context │\n")
(display " └─────────────────────────────────────────────────────────────┘\n\n")
(display " The difference:\n\n")
(display " Text says: 'grep searches for patterns in files'\n")
(display " Agent thinks: 'grep' is related to 'search' and 'files'\n")
(display " But doesn't know: exact syntax, output format, options\n\n")
(display " Execution shows:\n")
(display " $ grep bank corpus.txt\n")
(display " the customer deposited money at the bank\n")
(display " the fisherman sat on the bank\n")
(display " the river eroded the bank\n\n")
(display " NOW agent knows:\n")
(display " - Syntax: grep PATTERN FILE\n")
(display " - Output: matching LINES (not words, not files)\n")
(display " - Multiple matches returned\n")
(display " - Can find contexts for ambiguous words!\n\n")
;; ═══════════════════════════════════════════════════════════════════
;; THE CRITICAL DISCOVERY: GREP REDUCES VAGUENESS
;; ═══════════════════════════════════════════════════════════════════
(display "═══════════════════════════════════════════════════════════════════\n")
(display "CRITICAL DISCOVERY: grep Reduces Vagueness\n")
(display "─────────────────────────────────────────────────────────────────\n\n")
(display " The agent has high vagueness about 'bank' (multiple senses).\n\n")
(display " EXPERIMENT:\n")
(display " ───────────\n")
(display " Before: vagueness('bank') = 0.50\n\n")
(display " Action: grep bank corpus.txt\n")
(display " Result:\n")
(display " 'the customer deposited money at the bank'\n")
(display " 'the fisherman sat on the bank'\n")
(display " 'the river eroded the bank'\n\n")
(display " Agent processes these NEW examples:\n")
(display " - 'deposited money' + 'bank' → FINANCIAL sense\n")
(display " - 'fisherman sat' + 'bank' → GEOGRAPHIC sense\n")
(display " - 'river eroded' + 'bank' → GEOGRAPHIC sense\n\n")
(display " After: vagueness('bank') = 0.45\n")
(display " → Small improvement (more examples, same ambiguity)\n\n")
(display " BETTER EXPERIMENT:\n")
(display " ──────────────────\n")
(display " Action: grep 'river bank' corpus.txt\n")
(display " Result: Lines specifically about river banks\n\n")
(display " Action: grep 'financial bank' corpus.txt \n")
(display " Result: Lines specifically about financial banks\n\n")
(display " NOW the agent has DISCRIMINATING examples!\n")
(display " → Builds better sense-distinction model\n")
(display " → vagueness decreases more significantly\n\n")
(display " ┌─────────────────────────────────────────────────────────────┐\n")
(display " │ GROUNDED DISCOVERY: │\n")
(display " │ │\n")
(display " │ 'grep WORD FILE' returns contexts containing WORD │\n")
(display " │ More contexts → better PMI estimates → lower vagueness │\n")
(display " │ Specific queries → discriminating contexts → even better │\n")
(display " │ │\n")
(display " │ grep is a VAGUENESS-REDUCTION TOOL │\n")
(display " │ (discovered through actual use, not description) │\n")
(display " └─────────────────────────────────────────────────────────────┘\n\n")
;; ═══════════════════════════════════════════════════════════════════
;; PROGRESSION TO WEB SEARCH
;; ═══════════════════════════════════════════════════════════════════
(display "═══════════════════════════════════════════════════════════════════\n")
(display "PROGRESSION: From grep to Web Search\n")
(display "─────────────────────────────────────────────────────────────────\n\n")
(display " The agent has learned: grep searches LOCAL files.\n")
(display " But local corpus is LIMITED.\n\n")
(display " Continued exploration:\n\n")
(display " ACTION: curl --help\n")
(display " RESPONSE: 'curl - transfer a URL... -o write output to file...'\n")
(display " LEARNING: curl gets remote content\n\n")
(display " ACTION: curl http://example.com\n")
(display " RESPONSE: '<!doctype html><html>...Example Domain...</html>'\n")
(display " LEARNING: URLs return text content (HTML)\n\n")
(display " ACTION: curl 'https://en.wikipedia.org/wiki/Bank'\n")
(display " RESPONSE: [Large HTML about banks - financial and geographic]\n")
(display " LEARNING: Wikipedia has information organized by topic\n\n")
(display " CRITICAL EXPERIMENT:\n")
(display " ─────────────────────\n")
(display " ACTION: curl 'https://duckduckgo.com/?q=river+bank'\n")
(display " RESPONSE: [Search results about river banks]\n\n")
(display " ACTION: curl 'https://duckduckgo.com/?q=financial+bank'\n")
(display " RESPONSE: [Search results about financial banks]\n\n")
(display " PATTERN DISCOVERED:\n")
(display " URL + '?q=' + terms → results ABOUT those terms\n")
(display " This is a SEARCH ENGINE\n")
(display " It's like grep but for THE ENTIRE WEB\n\n")
;; ═══════════════════════════════════════════════════════════════════
;; THE ANSWER: BOTH, BUT EXECUTION IS ESSENTIAL
;; ═══════════════════════════════════════════════════════════════════
(display "═══════════════════════════════════════════════════════════════════\n")
(display "ANSWER: Can It Learn 'In Its Head'?\n")
(display "─────────────────────────────────────────────────────────────────\n\n")
(display " SHORT ANSWER: Partially, but execution is essential.\n\n")
(display " ┌─────────────────────────────────────────────────────────────┐\n")
(display " │ │\n")
(display " │ FROM TEXT ALONE ('in the head'): │\n")
(display " │ ✓ Can learn tool NAMES │\n")
(display " │ ✓ Can learn rough ASSOCIATIONS (ls ↔ files) │\n")
(display " │ ✓ Can form HYPOTHESES about what tools do │\n")
(display " │ ✗ Cannot VERIFY hypotheses │\n")
(display " │ ✗ Cannot learn exact SYNTAX │\n")
(display " │ ✗ Cannot learn OUTPUT FORMAT │\n")
(display " │ ✗ Cannot learn ERROR CONDITIONS │\n")
(display " │ ✗ Cannot DISCOVER that tools reduce vagueness │\n")
(display " │ │\n")
(display " │ FROM EXECUTION (grounded): │\n")
(display " │ ✓ All of the above │\n")
(display " │ ✓ VERIFIED knowledge (observed, not told) │\n")
(display " │ ✓ Precise syntax and patterns │\n")
(display " │ ✓ Actual effect on knowledge base (vagueness change) │\n")
(display " │ ✓ Can DISCOVER new tools through exploration │\n")
(display " │ │\n")
(display " └─────────────────────────────────────────────────────────────┘\n\n")
(display " THE KEY INSIGHT:\n\n")
(display " Text descriptions give HYPOTHESES.\n")
(display " Execution gives CONFIRMATION.\n\n")
(display " The agent could use text to GUIDE exploration:\n")
(display " 'The text mentions ls, cat, grep - try those first'\n\n")
(display " But it needs execution to GROUND the knowledge:\n")
(display " 'I ran ls and got a file list - now I KNOW what it does'\n\n")
;; ═══════════════════════════════════════════════════════════════════
;; HYBRID APPROACH
;; ═══════════════════════════════════════════════════════════════════
(display "═══════════════════════════════════════════════════════════════════\n")
(display "OPTIMAL: Hybrid Approach\n")
(display "─────────────────────────────────────────────────────────────────\n\n")
(display " PHASE 1: Learn from text (form hypotheses)\n")
(display " ──────────────────────────────────────────\n")
(display " Input: Man pages, tutorials, documentation\n")
(display " Output: Candidate commands, expected behaviors\n")
(display " Example: 'grep probably searches files for patterns'\n\n")
(display " PHASE 2: Test hypotheses (ground knowledge)\n")
(display " ───────────────────────────────────────────\n")
(display " Input: Candidate commands from Phase 1\n")
(display " Action: Execute and observe\n")
(display " Output: Confirmed/corrected tool models\n")
(display " Example: 'Confirmed: grep pattern file → matching lines'\n\n")
(display " PHASE 3: Explore beyond text (discover new)\n")
(display " ───────────────────────────────────────────\n")
(display " Input: Variations, combinations, random attempts\n")
(display " Action: Execute and observe\n")
(display " Output: Tools/patterns not in training text\n")
(display " Example: 'Discovered: curl URL | grep pattern works!'\n\n")
(display " PHASE 4: Close the loop (use tools for learning)\n")
(display " ────────────────────────────────────────────────\n")
(display " Input: High-vagueness topics\n")
(display " Action: Use search tools to get more text\n")
(display " Output: Lower vagueness, better knowledge\n")
(display " Example: 'Searched for river bank, got 1000 examples'\n\n")
;; ═══════════════════════════════════════════════════════════════════
;; MINIMAL IMPLEMENTATION
;; ═══════════════════════════════════════════════════════════════════
(display "═══════════════════════════════════════════════════════════════════\n")
(display "MINIMAL IMPLEMENTATION REQUIREMENTS\n")
(display "─────────────────────────────────────────────────────────────────\n\n")
(display " To actually build this, the agent needs:\n\n")
(display " 1. SHELL ACCESS (or equivalent text interface)\n")
(display " - Send: command string\n")
(display " - Receive: output string + exit code\n")
(display " - Timeout handling for hung commands\n\n")
(display " 2. REWARD SIGNAL\n")
(display " - +1 for informative output\n")
(display " - -0.5 for errors\n")
(display " - +2 for output that reduces vagueness\n")
(display " - -1 for destructive actions (learn to avoid)\n\n")
(display " 3. EXPLORATION STRATEGY\n")
(display " - Start with text-suggested commands\n")
(display " - Try --help on discovered commands\n")
(display " - Vary arguments systematically\n")
(display " - Combine tools (pipes)\n\n")
(display " 4. SAFETY CONSTRAINTS\n")
(display " - Sandbox/container environment\n")
(display " - Blacklist destructive commands (rm -rf, etc.)\n")
(display " - Rate limiting\n")
(display " - Undo capability where possible\n\n")
(display " 5. INTEGRATION WITH KNOWLEDGE BASE\n")
(display " - Text output → Layer 0-N processing\n")
(display " - Update co-occurrence counts\n")
(display " - Recalculate vagueness\n")
(display " - Trigger new queries if still uncertain\n\n")
;; ═══════════════════════════════════════════════════════════════════
;; SUMMARY
;; ═══════════════════════════════════════════════════════════════════
(display "═══════════════════════════════════════════════════════════════════\n")
(display "SUMMARY\n")
(display "─────────────────────────────────────────────────────────────────\n\n")
(display " Q: Can it learn tools 'in its head'?\n")
(display " A: Partially - but execution is required for grounded knowledge.\n\n")
(display " ┌─────────────────────────────────────────────────────────────┐\n")
(display " │ │\n")
(display " │ TEXT ALONE: │\n")
(display " │ → Hypotheses about tools │\n")
(display " │ → Unverified, possibly wrong │\n")
(display " │ → Like reading about swimming │\n")
(display " │ │\n")
(display " │ TEXT + EXECUTION: │\n")
(display " │ → Verified tool knowledge │\n")
(display " │ → Grounded in actual observation │\n")
(display " │ → Like actually swimming │\n")
(display " │ │\n")
(display " │ THE CRITICAL DISCOVERY: │\n")
(display " │ 'This tool reduces my vagueness' │\n")
(display " │ Can ONLY be learned through execution │\n")
(display " │ Because it requires measuring before/after │\n")
(display " │ │\n")
(display " └─────────────────────────────────────────────────────────────┘\n\n")
(display " The agent needs a shell (or API, or interface) to:\n")
(display " - Verify its hypotheses about tools\n")
(display " - Discover tools not mentioned in text\n")
(display " - Learn that certain tools reduce vagueness\n")
(display " - Actually use those tools to expand knowledge\n\n")
(display " This is the difference between:\n")
(display " 'Knowing about' (from text)\n")
(display " 'Knowing how' (from execution)\n\n")