Shell & Python

System Tools

execute_shell_command

Execute shell commands with timeout protection.

Requires Confirmation: Yes

Parameters:

Example:

Execute: ls -la /home/user

Returns: Command output (stdout + stderr) and exit code

execute_python

Execute Python code in a restricted environment with persistent state.

Requires Confirmation: Yes

Features:

• Persistent variables — Variables preserved between calls within a session
• REPL-style output — Last expression value automatically displayed
• True timeout — Enforced via subprocess isolation
• Execution history — Track past executions with %history
• Optional NumPy/Pandas — Automatically enabled if installed
• Special commands — %vars, %clear, %history, %modules, %help

Parameters:

Special Commands:

Core Modules:

math, random, string, re, json, datetime, collections, itertools, functools, operator, statistics, decimal, fractions, csv, dataclasses, enum, uuid, typing, base64, hashlib, textwrap, time, cmath, bisect, heapq

Optional Modules (if installed):

numpy ships in the cogtrix[science] extra. pandas and scipy are not installed by any Cogtrix extra, but if they are present in the active Python environment (e.g., a user-provided venv or a downstream image) they are accessible inside the sandbox.

Security Limits:

Security Features:

• AST Analysis — Deep inspection blocks dangerous attribute access
• Loop Limiting — Automatic iteration counter injection
• Recursion Control — Custom depth limit per subprocess
• Size Guards — Prevents memory exhaustion attacks

Restrictions:

• No file system access (open, pathlib)
• No network access (socket, urllib, requests)
• No system commands (os, sys, subprocess)
• No dangerous builtins (eval, exec, compile)
• No dangerous attributes (__class__, __bases__, __subclasses__, __globals__)

Examples:

Multi-step computation with persistent state:

Call 1: data = [1, 2, 3, 4, 5]
→ [Variables: data]

Call 2: avg = sum(data) / len(data)
→ Result: 3.0
  [Variables: avg, data]

Call 3: print(f"Average: {avg}")
→ Average: 3.0

REPL-style expression evaluation:

2 ** 10

→ Result: 1024

Using allowed modules:

import math
math.factorial(20)

→ Result: 2432902008176640000

View variables with types:

%vars

→

Variables:
  avg: float = 3.0
  data: list = [1, 2, 3, 4, 5]

View execution history:

%history 5

→

Last 5 execution(s):
  1. [10:15:01] ✓ data = [1, 2, 3, 4, 5]
  2. [10:15:05] ✓ avg = sum(data) / len(data)
  3. [10:15:10] ✓ 2 ** 10
  4. [10:15:15] ✗ undefined_var
  5. [10:15:20] ✓ %vars

Test Generation

generate_tests

Generate pytest test cases from a Python source file or function.

Parameters:

Returns: Generated test code as a string, ready to write to a test file.