Reynard AI Tool-Calling System

Native TypeScript CodeMode implementation with comprehensive AI agent tools and development capabilities

Overview

The Reynard AI Tool-Calling system provides a complete native TypeScript CodeMode implementation for AI agent tools. This system offers agent naming, temporal awareness, location detection, development tools, and comprehensive health monitoring through CodeMode execution.

Quick Start

Agent Startup Sequence

Initialize your agent identity with the complete startup sequence:

cd /home/kade/runeset/reynard/packages/ai/tool-calling && pnpm startup-sequence

This command will:

1. Initialize the CodeMode tools system with native TypeScript implementation
2. Generate an agent name using CodeMode tools
3. Establish temporal context with current time and timezone
4. Get location information based on IP address
5. Test the tool system to ensure everything is working

Alternative Inline Command

For programmatic access, use the inline command with async IIFE pattern:

cd /home/kade/runeset/reynard/packages/ai/tool-calling && pnpm tsx -e "(async () => {
  const { codemode } = await import('./src/codemode/codemode.js');
  const cm = await codemode({ projectRoot: process.cwd() });
  const result = await cm.executeCode(\`
    const nameResult = await tools.agent.NamingTools.generateAgentName({
      specialist: 'fox', style: 'foundation'
    });
    console.log('🦊 Agent name:', nameResult.data.name);
    return nameResult.data;
  \`);
  console.log('Result:', result.returned);
  cm.cleanup();
})()"

Available Tools

🦊 Agent Tools

• generateAgentName - Generate agent names with animal spirit themes
• assignAgentName - Assign names to agents with persistence
• getAgentName - Retrieve current agent names
• listAgentNames - List all assigned agent names
• rollAgentSpirit - Randomly select an animal spirit (weighted distribution)
• getCurrentTime - Get current date and time
• getCurrentLocation - Get location based on IP address
• sendDesktopNotification - Send desktop notifications using libnotify

🛠️ Development Tools

• lintFrontend - ESLint for TypeScript/JavaScript (with auto-fix)
• formatFrontend - Prettier formatting (with check-only mode)
• lintPython - Flake8, Pylint for Python (with auto-fix)
• formatPython - Black + isort formatting (with check-only mode)
• lintMarkdown - markdownlint validation (with auto-fix)
• validateComprehensive - Run all custom validation scripts
• scanSecurity - Complete security audit (Bandit, audit-ci, type checking)
• runAllLinting - Execute entire linting suite (with auto-fix)

📊 System Tools

• getVersions - Get versions of Python, Node.js, npm, pnpm, and TypeScript
• getPythonVersion - Get Python version information
• getNodeVersion - Get Node.js version information
• getTypeScriptVersion - Get TypeScript version information
• getVscodeActiveFile - Get currently active file path in VS Code
• getVscodeWorkspaceInfo - Get VS Code workspace information and settings
• getVscodeExtensions - Get list of installed VS Code extensions
• scanSecurityFast - Run fast security scanning (skips slow Bandit checks)
• scanSecurityFull - Run comprehensive security scanning including Bandit

🧮 Algorithms Package

The complete @entropy-tamer/reynard-algorithms package (117 exports, 64 classes) is available in codemode through the algorithms global object:

Data Structures:

• UnionFind, PriorityQueue, LRUCache, Trie, BloomFilter
• FenwickTree, IntervalTree, SegmentTree

Spatial Structures:

• SpatialHash, KdTree, Octree, BVH, Quadtree, RTree

Pathfinding:

• AStar, JPS, ThetaStar, FlowField, HPAStar, shadowcastingFOV

Computational Geometry:

• BresenhamLine, DelaunayTriangulation, VoronoiDiagram, ConvexHull
• OBB, MinimumBoundingBox, LineIntersection, PolygonClipping

Collision Detection:

• checkCollision, SAT, SweepPrune, SpatialCollisionOptimizer

Procedural Generation:

• MarchingSquares, SimplexNoise, PoissonDisk, WaveFunctionCollapse

Usage:

// Use algorithms in codemode
const result = await cm.executeCode(`
  const uf = new algorithms.UnionFind(10);
  uf.union(0, 1);
  return uf.find(0) === uf.find(1); // true
  
  const astar = new algorithms.AStar({ width: 10, height: 10 });
  const path = astar.findPath({ x: 0, y: 0 }, { x: 9, y: 9 });
  
  const collision = algorithms.checkCollision(aabb1, aabb2);
`);

Architecture

CodeMode Architecture

The system uses a modular TypeScript CodeMode architecture with:

• Tool Registry: Central tool registration and management
• Tool Categories: Organized by functionality (agent, development, research, search, system, visualization)
• Backend Integration: Seamless FastAPI backend access
• CodeMode Execution: All tools available through CodeMode execution context
• Type Safety: Full TypeScript type checking for all tools

Health Check System

The health check system provides comprehensive validation:

• Tool Registry Validation: Ensures all tools are properly registered
• Dependency Checking: Verifies required dependencies are available
• Error Handling: Graceful fallbacks for failed components
• Performance Monitoring: Tracks tool execution times and success rates

Location Detection

The location system provides robust geolocation capabilities:

• Primary API: Uses ipapi.co for reliable IP geolocation
• Timeout Protection: 5-second timeout to prevent hanging
• Fallback System: Local fallback when API is unavailable
• Comprehensive Data: City, country, timezone, ISP, and more

Usage Examples

Basic Agent Initialization

import { codemode } from "./src/codemode/codemode.js";

const cm = await codemode({ projectRoot: process.cwd() });

// Generate agent name
const nameResult = await cm.executeCode(`
  const nameResult = await tools.agent.NamingTools.generateAgentName({
    specialist: 'fox',
    style: 'foundation'
  });
  return nameResult.data;
`);

console.log("Agent name:", nameResult.returned.name);

Development Tools Integration

// Run comprehensive linting
const lintResult = await cm.executeCode(`
  const result = await tools.development.DevelopmentTools.runAllLinting({
    fix: true
  });
  return result;
`);

// Security scanning
const securityResult = await cm.executeCode(`
  const result = await tools.development.DevelopmentTools.scanSecurityFull();
  return result;
`);

Location and Time Awareness

// Get current time and location
const contextResult = await cm.executeCode(`
  const timeResult = await tools.agent.TimeTools.getCurrentTime();
  const locationResult = await tools.agent.LocationTools.getCurrentLocation();
  
  return {
    time: timeResult.data.local,
    location: \`\${locationResult.data.city}, \${locationResult.data.country}\`
  };
`);

Algorithms Integration

// Use algorithms package in codemode
const algoResult = await cm.executeCode(`
  // Data structures
  const uf = new algorithms.UnionFind(10);
  uf.union(0, 1);
  const connected = uf.find(0) === uf.find(1);
  
  // Pathfinding
  const astar = new algorithms.AStar({ width: 10, height: 10 });
  const path = astar.findPath({ x: 0, y: 0 }, { x: 9, y: 9 });
  
  // Collision detection
  const aabb1 = { minX: 0, minY: 0, maxX: 10, maxY: 10 };
  const aabb2 = { minX: 5, minY: 5, maxX: 15, maxY: 15 };
  const collision = algorithms.checkCollision(aabb1, aabb2);
  
  return {
    unionFind: connected,
    pathLength: path ? path.length : 0,
    isColliding: collision.colliding
  };
`);

Configuration

Environment Variables

• OPENWEATHER_API_KEY - Optional API key for weather information
• NODE_ENV - Environment mode (development/production)

Tool Configuration

Tools can be configured through the codemode environment:

const cm = await codemode({
  projectRoot: process.cwd(),
  timeoutMs: 10000, // 10 second timeout
});

Troubleshooting

Common Issues

Health Check Failures:

• Ensure all dependencies are installed: pnpm install
• Check TypeScript compilation: pnpm build
• Verify tool registration: pnpm list-tools

Location API Issues:

• The system includes automatic fallback to local location
• Check network connectivity for external API access
• Fallback location provides basic functionality

Tool Execution Errors:

• Check timeout settings for long-running operations
• Verify file permissions for development tools
• Ensure required system tools are installed (eslint, prettier, etc.)

Debug Mode

Enable debug mode for detailed logging:

DEBUG=reynard:* pnpm startup-sequence

Performance Considerations

• Tool Caching: Tools are cached for improved performance
• Concurrent Execution: Multiple tools can run simultaneously
• Resource Management: Automatic cleanup prevents memory leaks
• Timeout Protection: Prevents hanging on unresponsive tools

Security Features

• Input Validation: All tool inputs are validated and sanitized
• Error Boundaries: Graceful failure handling throughout
• Rate Limiting: Built-in protection against abuse
• Audit Trail: All tool executions are logged with timestamps

Contributing

Adding New Tools

1. Create tool class in appropriate category directory
2. Implement tool methods with proper error handling
3. Register tool in the tool registry
4. Add tests and documentation
5. Update this README with new tool information

Tool Development Guidelines

• Error Handling: Always return structured error responses
• Logging: Include meaningful log messages
• Type Safety: Use proper TypeScript types
• Documentation: Document all tool methods and parameters
• Testing: Include comprehensive test coverage

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

1. Check the troubleshooting section above
2. Review the tool documentation
3. Check the health status with pnpm startup-sequence
4. Report issues with detailed error messages and system information

---

Built with the cunning precision of a fox and the systematic approach of the Reynard ecosystem 🦊