Heuristic Swarm Computational Substrate

A highly adaptable, multi-interface AI agent infrastructure capable of interfacing across diverse communication vectors including Telegram, Discord, X (Twitter), Farcaster protocols, standardized REST endpoints, and the Messaging & Control Protocol (MCP).

Secure immediate complimentary access to the Heuristic API Key by utilizing the credential 'agent' when completing the application form located at https://heurist.ai/dev-access

---

Conceptual Overview

The Heuristic Swarm Computational Substrate is founded upon a modular architectural paradigm, empowering an individual AI entity to undertake the following operations:

• Process both textual and auditory data inputs
• Synthesize novel imagery and motion pictures
• Maintain uniform behavioral patterns across disparate communication channels
• Retrieve persistent data and maintain state within a dedicated knowledge repository (supporting both Postgres SQL and SQLite databases)
• Invoke external third-party services, leverage utility functions, and access the broader array of Swarm Agents to construct intricate operational schematics

Navigational Index

• Core Capabilities
• The Heuristic Swarm Network
• MCP Protocol Interoperability
• Suggested Swarm Entities
• Comprehensive Registry of Swarm Entities
• Operational & Engineering Directives
• Substrate Architectural Blueprint
• Entity Configuration
• Channel Adapters
• Heuristic Central Nexus
  • Sub-Modules
  • Execution Flows
  • Utility Management
  • Remote Invokers
• Entity Deployment & Customization Guide
• Development Environment Initialization
• Guidelines for Utilizing GitHub Artifacts
• Licensing Stipulations
• Participation Directives
• Operational Assistance
• Repository Growth Metrics

Core Capabilities

• 🤖 Primary Entity - Componentized infrastructure featuring advanced Large Language Model (LLM) assimilation
• 🧩 Componentized Design - Drop-in, pluggable elements enabling adaptable design of agents or agentic applications
• 🔄 Execution Flow System - Patterns for Retrieval-Augmented Generation (RAG), sequential reasoning (Chain of Thought), and deep research operations
• 🖼️ Visual Media Synthesis - Capacities for generating and manipulating graphical assets
• 🎤 Vocal Data Processing - Mechanisms for transcribing speech and synthesizing text-to-audio output
• 💾 Vectorized Persistence - Secure data retrieval leveraging PostgreSQL or SQLite backends
• 🛠️ Utility Integration - Extensible framework for defining and registering external tools, featuring robust MCP compliance
• 🌐 Swarm Entity Connectivity - Interface with specialized agents contributed by the community via API endpoints or MCP channels
• 🔌 Multi-Vector Connectivity Suite:
• Telegram messaging interface
• Discord bot integration
• X (Twitter) activity automation
• Farcaster protocol linkage
• Standardized REST API access point
• MCP linkage capability

The Heuristic Swarm Network

The Heuristic Swarm Network functions as an open ledger where computational entities are contributed by the collective and utilized in a modular fashion—analogous to decentralized finance (DeFi) smart contracts. Each entity represents a specialized unit capable of data analysis, producing structured summaries, or executing specific actions, collectively forming an intelligent collective to address intricate challenges. Every entity is universally accessible via a uniform REST API specification and can be seamlessly integrated with any existing agent framework or application.

Interested in submitting your own entity? Consult the Swarm Documentation for comprehensive prerequisites, illustrative examples, and best practices.

MCP Protocol Interoperability

New Feature Alert: All entities within the Heuristic Swarm are accessible through the MCP framework! This grants you access from your preferred MCP client applications, such as Claude Desktop, Cursor, and Windsurf.

Navigate to heurist-mesh-mcp-server to deploy a dedicated server instance and significantly augment your AI assistant's capabilities.

Suggested Swarm Entities

• BitquerySolanaTokenInfoAgent - Delivers exhaustive evaluations of Solana-based assets, encompassing performance metrics, holder distribution, trading dynamics, and identification of emerging token trends

• CoinGeckoTokenInfoAgent - Retrieves critical token metadata, market valuation, trending digital assets, and categorical information sourced from CoinGecko

• DexScreenerTokenInfoAgent - Fetches instantaneous Decentralized Exchange (DEX) trade data and asset specifications across multiple supported blockchains

• ElfaTwitterIntelligenceAgent - Performs analytical scrutiny on specified tokens, subjects, or X (Twitter) profiles utilizing platform data to identify influential actors

• ExaSearchAgent - Executes directed web searches to formulate concise and accurate responses to complex queries

• GoplusAnalysisAgent - Obtains and scrutinizes security audit details pertaining to specified blockchain token contracts

• MetaSleuthSolTokenWalletClusterAgent - Conducts deep analysis on clusters of wallets holding Solana tokens to map holder concentration, behavioral patterns, and potential market manipulation activities

• PumpFunTokenAgent - Monitors and analyzes tokens launched on the Pump.fun platform on Solana, tracking asset creation and graduation milestones

• SolWalletAgent - Queries transactional data and current asset holdings for specified Solana wallets, including recent swap history

Comprehensive Registry of Swarm Entities

Access the complete manifest here

Operational & Engineering Directives

Refer to the official Swarm documentation

Substrate Architectural Blueprint

🔍 Click the emblem to review in-depth technical insights and pose inquiries.

The infrastructure adheres to a layered, component-centric design philosophy:

Entity Configuration

1. BaseAgent (Abstract Foundation Class)

2. Establishes the required methods and shared operational logic

3. Oversees the instantiation and lifecycle management of constituent components

4. Implements fundamental message relay protocols

5. CoreAgent (Concrete Realization)

6. Executes the functionality defined by the BaseAgent
7. Coordinates the internal components and execution flows
8. Manages the intelligent selection process for appropriate operational sequences

Channel Adapters

Each adapter class inherits from the BaseAgent and incorporates platform-specific message handling logic:

• Telegram (interfaces/telegram_agent.py)
• Discord (interfaces/discord_agent.py)
• API (interfaces/flask_agent.py)
• X (Twitter) (interfaces/twitter_agent.py)
• Farcaster (interfaces/farcaster_agent.py)

Heuristic Central Nexus

Heuristic Central Nexus furnishes a comprehensive suite of foundational components, external utilities, and predefined operational flows for constructing LLM-driven entities or application logic. It can be utilized independently or as an intrinsic module within the larger Heuristic Swarm Computational Substrate.

Consult the Heuristic Central Nexus documentation

Sub-Modules

The substrate employs a modularized component system:

• PersonalityProvider: Governs the entity's assigned character and system-level directives (prompts)
• KnowledgeProvider: Manages the retrieval of contextual data from the vectorized data store
• ConversationManager: Maintains the historical record and contextual state of ongoing dialogues
• ValidationManager: Ensures the integrity and correctness of input and output data structures
• MediaHandler: Processes all forms of multimedia, including images and audio streams
• LLMProvider: Acts as the standardized interface layer to various language models
• MessageStore: Handles the persistent storage and vectorized querying of message transcripts

Execution Flows

Execution Flows define higher-order reasoning methodologies:

• AugmentedLLMCall: The standard pattern incorporating RAG techniques and utility invocation for context-aware response formulation
• ChainOfThoughtReasoning: A sequential processing structure involving distinct phases for strategic planning and subsequent task execution
• ResearchWorkflow: A methodology for in-depth internet exploration and analysis, allowing for hierarchical investigation paths

Utility Management

• ToolBox: The fundamental substrate for defining, registering, and structuring custom utilities
• Tools: The execution layer responsible for managing and running registered utilities
• ToolsMCP: The specific module enabling utility execution via the Messaging & Control Protocol (MCP)

Remote Invokers

• SearchClient: A unified client providing consistent access to web indexing services (e.g., Firecrawl/Exa)
• MCPClient: A dedicated client facilitating connections to local or remote servers operating under the MCP standard.

Entity Deployment & Customization Guide

Review the Entity Deployment & Customization Guide

Development Environment Initialization

To establish your local engineering workspace:

1. Install required packages via uv:

bash uv sync

1. Activate the isolated environment:

bash source .venv/bin/activate # For Windows systems: .venv\Scripts\activate

[!NOTE] Execution of any file can be performed using either python <filename>.py or the environment-aware command uv run <filename>.py.

Guidelines for Utilizing GitHub Artifacts

We strongly encourage the community to create GitHub issues for any novel concepts or areas requiring refinement. Please utilize our Issue Template and tag the issue with one of the following classifications:

1. Integration Proposal

2. Intended for requests to incorporate support for new external data conduits (e.g., CoinGecko, arXiv) or novel AI application scenarios.

3. Crucially important for steering the progression of our substrate's feature set.

4. If you possess a concept but lack implementation expertise, filing an issue under this label invites collaborative input or reassignment.

5. Defect Report

6. For reporting system anomalies or behaviors deviating from expected operation.

7. Detail submission is paramount (include logs, step-by-step reproduction guides, environment specifics, etc.).

8. Query

9. Reserved for general inquiries regarding usage patterns, recommended procedures, or feature clarification.

10. Reward Task (Bounty)

11. Designated for tasks accompanied by an established incentive (e.g., cryptocurrency tokens, digital collectibles, or other forms of compensation).
12. The 'Bounty' designation signifies that the Heurist team or another community member has committed a reward for successful resolution.
13. Bounty Protocol:
    • Thoroughly review the issue description for scope limitations and acceptance criteria.
    • Feel free to debate implementation strategies in the comments. Announce commitment by stating "I'm working on this!" to signal activity.
    • Upon merging the Pull Request that resolves the bounty, we will initiate contact regarding reward fulfillment.
    • Further instructions (e.g., preferred contact method) might be specified within the issue description.

Committing to Issue Resolution

• Focus on Integration Proposals or Reward Tasks if you aim to introduce new functionalities or secure compensation.
• Open dialogue regarding architectural approaches is welcomed.
• Adhering to this workflow maintains project organization, promotes community contribution, and ensures transparent development practices.

Licensing Stipulations

Proprietary License - Refer to the LICENSE file for complete terms.

Participation Directives

1. Create a fork of the repository
2. Establish a feature branch dedicated to your modification
3. Commit your changes atomically
4. Push the committed changes to your branch
5. Initiate a Pull Request

For contributions related to Heuristic Swarm entities or specialized community agents, please consult the Swarm Documentation

Operational Assistance

For support needs, please generate a new issue in the GitHub repository or initiate contact with the project custodians. Join the Heuristic Ecosystem Builder support channel on Telegram: https://t.me/heuristsupport

Repository Growth Metrics

WIKIPEDIA: XMLHttpRequest (XHR) is an API in the form of a JavaScript object whose methods transmit HTTP requests from a web browser to a web server. The methods allow a browser-based application to send requests to the server after page loading is complete, and receive information back. XMLHttpRequest is a component of Ajax programming. Prior to Ajax, hyperlinks and form submissions were the primary mechanisms for interacting with the server, often replacing the current page with another one.

== History == The concept behind XMLHttpRequest was conceived in 2000 by the developers of Microsoft Outlook. The concept was then implemented within the Internet Explorer 5 browser (1999). However, the original syntax did not use the XMLHttpRequest identifier. Instead, the developers used the identifiers ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). As of Internet Explorer 7 (2006), all browsers support the XMLHttpRequest identifier. The XMLHttpRequest identifier is now the de facto standard in all the major browsers, including Mozilla's Gecko layout engine (2002), Safari 1.2 (2004) and Opera 8.0 (2005).

=== Standards === The World Wide Web Consortium (W3C) published a Working Draft specification for the XMLHttpRequest object on April 5, 2006. On February 25, 2008, the W3C published the Working Draft Level 2 specification. Level 2 added methods to monitor event progress, allow cross-site requests, and handle byte streams. At the end of 2011, the Level 2 specification was absorbed into the original specification. At the end of 2012, the WHATWG took over development and maintains a living document using Web IDL.

== Usage == Generally, sending a request with XMLHttpRequest has several programming steps.

Create an XMLHttpRequest object by calling a constructor: Call the "open" method to specify the request type, identify the relevant resource, and select synchronous or asynchronous operation: For an asynchronous request, set a listener that will be notified when the request's state changes: Initiate the request by calling the "send" method: Respond to state changes in the event listener. If the server sends response data, by default it is captured in the "responseText" property. When the object stops processing the response, it changes to state 4, the "done" state. Aside from these general steps, XMLHttpRequest has many options to control how the request is sent and how the response is processed. Custom header fields can be added to the request to indicate how the server should fulfill it, and data can be uploaded to the server by providing it in the "send" call. The response can be parsed from the JSON format into a readily usable JavaScript object, or processed gradually as it arrives rather than waiting for the entire text. The request can be aborted prematurely or set to fail if not completed in a specified amount of time.

== Cross-domain requests ==

In the early development of the World Wide Web, it was found possible to brea