Metadata-Version: 2.4
Name: xFS_bots
Version: 0.0.4
Summary: A suite of offline bots built on top of classical NP-Complete problems. Friendly for cryptographic operations.
Home-page: https://github.com/Changissnz/xFS
Author: Richard Pham
Author-email: Richard Pham <phamrichard45@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/changissnz/xFS
Project-URL: Issues, https://github.com/changissnz/xFS/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy>=1.22.1
Requires-Dist: matplotlib>=3.10.9
Requires-Dist: morebs2>=0.1.99
Requires-Dist: networkx>=3.6.1
Dynamic: author
Dynamic: home-page
Dynamic: license-file

# xFS_bots 

See this [Github link](https://www.github.com/changissnz/xfs) for more information. 

## Graph Problems of Interest (in my words)

Here is a list of graph problems in the project: 
- Respondent Network Bot (Alpha) 
    - vantage point for learning: Q, the questioner. 
    - file: `graph_problems/rnb.py`
- Hidden Threat Exposure Bot (Alpha) 
    - vantage point for learning: navigator of network containing threats. 
    - file: `graph_problems/hte.py`
- Slander Net Bot (Alpha)  
    - vantage point for learning: agent that determines what communication 
      ports to open and close to maximize objective function score. 
    - code has non-deterministic elements to it. Required to set seeds for 
    Python and Numpy random. 
    - file: `graph_problems/snb.py`
- Poison Trace Bot (Alpha) 
    - vantage point for learning: agent (poison target), in a network, that 
    has to position alert relays to help it know (poison source, poison identity) 
    of poison delivered to it. Accurate knowledge allows for poison target to 
    negate poison before its termination. 
    - code has non-deterministic elements to it. Required to set seeds for 
    Python and Numpy random.
    - file: `graph_problems/ptb.py`  
- Bull Killer Bot (Alpha) 
    - vantage point for learning: Chaser agents that pursue the Bull along a 
    network. 
    - file: `graph_problems/bkb.py` 
- Homo Frame Bot (Alpha) 
    - vantage point for learning: n agents expected to act according to 
    homomorphic demands, set by administrator. 
    - file: `graph_problems/hfb.py` 
- Mob Killer Bot (Alpha) 
    - vantage point for learning: anti-mob unit acting against `n` Mob agents in 
    a reactive system. 
    - file: `graph_problems/mkb.py` 
- Strangle Bot (Alpha)  
    - vantage point for learning: strangling agent with objective to control all nodes 
    of graph G, the subject of strangling. 
    - file: `graph_problems/sb.py` 
- Controverter Bot (Alpha) 
    - vantage point for learning: an agent in a multi-agent cyclical game, structured as a 
    continually variable chain of decision junction points, each requiring all the 
    agents to make their moves. 
    - file: `graph_problems/cb.py` 
- Token-Swapping Bot (Alpha) 
    - vantage point for learning: an agent that has to solve the NP-Complete problem, Token Swapping, 
    for an arbitrary graph. 
    - file: `graph_problems/tsb.py` 
- Dual Role Bot (Alpha) 
    - vantage point for learning: a dual agent that has to complete n demands, each demand consisting 
    of an independent and a third-party component, with the least cost from conflicts of independence 
    within and between the demands.  
    - NOTE: problem can be reduced to the NP-Hard problem, Set Cover. 
    - file: `graph_problems/drb.py`  
- Middleman Bot (Alpha)
    - vantage point for learning: a buying agent that is to buy x units of a product through a network 
        of sellers, the network starting with one original seller and n middle agents, at the lowest 
        cumulative price.  
    - file: `graph_problems/mmb.py`  
- Vector-Tracking Bot (Alpha)  
    - vantage point for learning: a group of n > 1 tracking agents that is to track a moving 
        target, over q rounds, with the primary goal of minimal cumulative euclidean distance 
        with the target and the secondary goal of maintaining symmetric balance with one another.  
    - file: `graph_problems/vtb.py`  
- Introspection Bot (Alpha) 
    - vantage point for learning: obtaining the same cyclical node output and shortest paths as a 
        reference result in a simple undirected graph, traversed through a breadth-first or depth-first 
        process. 
    - file: `graph_problems/ib.py` 
- Probabilistic Impact Bot (Alpha)
    - vantage point for learning: defending against each of an offendor's moves by correctly predicting the 
        move; based on the Hidden Markov Model. 
    - file: `graph_problems/pib.py` 
- Ends-Fixated Bot (Alpha)
    - vantage point for learning: navigating a directed graph from start node to end node, such that each 
        node is associated with an activation function navigator must pass, via providing appropriate 
        support values (real numbers) to the nodes of relevance. 
    - file: `graph_problems/efb.py` 
- Two Faces Three Motives Bot (Alpha)
    - vantage point for learning: an agent, connected to two other agents in a trifecta arrangement, that 
        has to execute its independently selected move at every timestamp. 
    - file: `graph_problems/tftmb.py`
- Proaction-Driven Inadvertency Bot (Alpha) 
    - vantage point for learning: executing n three-noded steps with the least number of inadvertencies 
       activated.
    - file: `graph_problems/pdib.py`

#### NOTE: 
Some of these bots rely on Python/Numpy random. User results may differ from 
developer results. As of this time in writing, developer Python version is 3.14.2. 


#### NOTE: 
The methods provided in `file<graph_problems.easy_gen>` allow for easy generation of 
these bots (less instantiating parameters). 

## Starting Out 

PRNGs are required to operate these bots. Here is a simple script that uses `xFS_bots`'
easy generation scheme to produce a bot. 

```
from xFS_bots.graph_problems import easy_gen
from morebs2.numerical_generator import prg__LCG

prg = prg__LCG(5254.235235,235235.234523,235423.23523,235235.2323)
probabilistic_impact_bot = easy_gen.easy_generate_PIBot(prg)
next(probabilistic_impact_bot)
``` 

For more information, please visit the link provided at the top of this file. 

## The Machine-Learning Aspect 

The graph problems defined in this project involve software agents. These agents are 
programmed with functionalities that are static. This implies the agents cannot "learn" 
any more, past their programming, about the specific problems they act in. Their learning 
mechanisms cannot "expand" any more outside of this static programming: no additional 
variables of interest, no different data structure formats, no different ordering scheme 
of deciding on the best choice per timestamp, no different ranking mechanisms for choices. 
Instead, the only way to improve a solution is through a semi-blind search process that iterates 
through a candidate list of pseudo-random number generators (PRNGs) for the best PRNG. 
PRNGs are used in agent decision-making for these graph problems. PRNGs output numbers, 
and agents map these numbers out to decisions taken by them. The utility of obtaining a 
high-performing PRNG for a graph problem of specific starting parameters is restricted to 
that case. There is no software mechanism provided to automate deriving of further insight 
into any graph problem example via a high-performing PRNG. This deficit differs from 
traditional machine-learning problems on fixed and labeled datasets, where feedback loops 
of training iterations can be guaranteed to yield incrementally better solutions, until 
the global optimum is found. This guarantee, of course, is theoretical and cannot be stated for 
deep learning problems on highly variable datasets. It is possible to implement further 
code for these graph problems to be more conducive for machine-learning. However, 
implementing further code would defeat the purpose of graph problem difficulty. The 
division of partial information between agents in every one of these graph problems was 
deliberate in fulfillment of maintaining a baseline of probabilistic difficulty for an agent 
to improve its solution (PRNG). Unlike the highly vectorizable (input,output) samples 
of traditional machine-learning that typically operates in Euclidean space, finding a 
high-scoring solution does not easily lead to a better solution derived from that one. 
Users can refer to one high-scoring PRNG, and add tweaks to it at selected indices of 
the generator output. See below for illustration on PRNG G and tweaking it to G2: 
```
G:  x0,x1,x2,x3,x4,x5... 
G2: x0,x42,x2,x56,x4,x5,... 
```

But this is a cumbersome process, and there is no guarantee making tweaks to a high-performing 
generator would result in a better solution. 

## User Access to the Graybox 

The computer code for these bots in these graph problems is open for view. This is not a 
blackbox arrangement. Users, in their attempts to guess high-performing PRNGs for any 
graph problem example, can carefully review how the automata decision-making pipelines 
work. These pipelines follow a general form, and descriptions are provided for each of 
these graph problem bots. But these implementations rest on arbitrary design. 

In a blackbox system, users would not know what the graph problem is, let alone the general 
form of it. They would only be able to enter in a PRNG for the automaton to use for 
decision-making. They would not be able to ascertain the end results from the PRNG. In these 
graybox implementations, users would know the end results from the PRNG. But since a 
PRNG only outputs real numbers for decision-making, users would not be able to easily know 
what decisions the PRNG was responsible for. Thus, users would have a relatively difficult 
time knowing what decisions are sub-optimal. Users can analyze the code implementation to 
determine the specific decisions the PRNG mapped to, post-simulation. But code is not 
provided in this project to convenience that.  
