Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
460 lines (352 loc) · 33.4 KB

CONTRIBUTING.md

File metadata and controls

460 lines (352 loc) · 33.4 KB

Why Contribute?

What economic system enables a Kardashev Type 1 civilization? Do you really think it's what we've got now?

What happens when AI and robots swallow jobs wholesale? Print money for UBI and hope you don't need a wheelbarrow full of cash to buy a loaf of bread next year?

What if we can turn job replacement into an economic system's strength, even its primary growth factor, rather than a death sentence?

Does anyone saying "The future is abundance" with starry-eyed fever pitch have any clue what that actually means, or is it baseless hype?

Project-Asimov isn't selling dreams: it's old-fashioned hard work today applied to the problems of tomorrow.

Maybe Robonomics is a terrible idea. Then again, maybe it's Kardashev 1+ economics. Project Asimov is the place for people who want to make tangible progress toward making that call.

If you so choose, this is where your contribution begins.

If you're thinking of contributing or if you already are contributing and need a refresher, this is where you can get the nitty-gritty details on the Asimov system architecture.

Let's Get Housekeeping Out of the Way

As the official design document, this is the One Source of Truth. If it's not here, it's not yet Project-Asimov canon. If you think something in this document contradicts itself, please raise a docs issue on our Issues Board before you do anything else and forget. When writing new documentation or code, check here first so you understand how your feature fits into the grand scheme of things.

Before you can merge any feature or fix to main, it will need to be fully documented, too. If that documentation means this or anything else needs to change, submit an issue for tracking.

What I'm getting at is this document needs to be up to date and correct, or bad things happen.

I'm Jon, by the way, the current Owner and Manager of Project Asimov, until someone smarter and better comes along, at least.

Quick Point of Clarification

"Asimov" refers to the Python Package. "Project-Asimov" is the open source effort to create "Asimov". Robonomics.py is the Python class that contains an entire Robonomic/RoboTorq Economy. We'll be doing lots of defining in this document.

The Basics

Project-Asimov runs on Python 3.13.

Overview

Simulating any economy in a pseudo-realistic fashion requires modeling a massive, nearly infinitely tangled web of interactions... Oof, sounds complicated. Maybe it will get better?

Naturally, we'll need to name all the parts of this simulated economy to discuss it in any meaningful way, much more so to code it!

The economy is a complex data structure known as a graph, actors are nodes in the graph, and flow are edges that... OK, well, that was even worse. Let's try this another way.

Robonomics Lingo Really Does Help Simplify Things

...once you understand a few basic terms. Thankfully, you have this guide. It helps if you think of this like a video game world. actors are the characters, and flows are the things they can do.

Two Steps Back In excruciatingly necessary terms: Each flow is designed to move a single type of thing, for one particular reason, between two unique actors, in only one direction, at a fixed rate, according to each actor's attribute schema, for an prescribed duration, at which point, it is always responsible for flagging itself for removal from the economy.

The naming conventions are designed to distance conversation from the underlying data structures through abstraction, allowing anyone to discuss the simulation without understanding computer science jargon. Let's use the three terms we've already defined in an example.

  • Example: Every Bondholder is connected to Isaac via a persistent DistoStream flow.

There is a lot of information encoded in that sentence.

Let's unpack what that means in more exact terms, so you can see how the abstraction focuses on WHAT the data represents, rather than HOW the underlying data structure gets the job done.

  • A Bondholder owns at least one Bond signifying shared ownership of a humanoid Robot.
  • Isaac is the node that mints and distributes RoboTorq to Bondholder nodes, which happens via a edge that connects each node.
  • A DistoStream is the specific type of graph edge connecting the two nodes, we call any edge a flow (flows italicized in this doc so you can tell the difference)
  • It is "persistent" because this particular flow will last longer than one cycle of the simulation.
  • Asimov's simulation cycle timer proceeds using two different mechanisms, ticks and steps, more on those later.

Once again: Each flow is designed to move a single type of thing, for one particular reason, between two unique actors, in only one direction, at a fixed rate, according to each actor's attribute schema, for an prescribed duration, at which point, it is always responsible for flagging itself for removal from the economy.

Once you really internalize this key mechanism of moving data through the economy, the rest is easy.

The Perfect Flow Analogy?

Imagine you have a blow gun that shoots one dart at a time. In this example, each dart would be a flow moving from one actor, you, the source, to another actor, the target.

You have three kinds of darts.

  • One is a normal dart. You shoot it, it either hits its target or misses.
  • Another has a string attached to it.
    • If you hit your target, you can pull the string tight and transfer messages along it like with two cups and a string as long as its stuck in the target.
    • This is a persistent flow.
  • The final kind of dart is very special.
    • If this dart hits its target, it can shoot more darts and hit other targets automatically.
    • And some of those are special darts as well, they shoot their own darts if they hit their targets.
    • But you, the actor who shot it, are responsible for making sure you hit the initial target.
    • And if you're expecting something in return, and don't get it, you're also responsible for shooting another dart.
  • We, the programmers, are responsible for making sure misses don't happen, and that if they do, the program doesn't crash.

Keep this in mind as you read through the following sections, and the RoboTorq economy will take shape in your mind soon enough.

Other Key Terms & Data Structures

From here, we can start defining key terms more readily.

  • Registries like BondholderRegistry (a Polar DataFrame for storing attributes of every node) and EnterpriseRegistry (for enterprises).
  • Models map Registries to the Economy's graph structure. Every data structure inside the simulation can interact with each other through this class: src/asimov/models/robonomics.py
  • Oracles track the activity of Robots as they produce.
  • RoboTorq is the currency itself, backed by the realized productive output of the Bond Network's fleet as a whole.
  • Torq is a metric used to help in internal Oracle and Production auditing/tracking, as well as the valuation of production.
  • TokenTorq is almost like an internal exchange rate, used to quantify the AI requirements of robotic production within the Torq measurement process, assisting with the valuation of RoboTorq.

Systemic Actors and Their Interactions in Detail (Ideal Simulation Behavior)

A hypothetical "real" RoboTorq Economy would have several AI actors managing the various subsystems, allowing the Bondholders and Enterprises to interact with each other smoothly. In this section, all boxes that look like this denote nodes (i.e. actors only).

This section will go into extreme detail. You should be able to reference this document and understand the place of your work within the grand scheme of the RoboTorq Economy.

How RoboTorq Gets into the Economy

  • Isaac is the RoboTorq Economy's AI mint and distribution hub.
  • Bondholders receive a constant trickle of RoboTorq from Isaac, 24/7/365.
  • This constant trickle is called a DistoStream flow (specific instances of flows, like DistoStream, will also be italicized to separate the two ideas)

How RoboTorq moves through the Economy: Spending & Investing

  • Enterprises sell goods and services to Bondholders with a SellsToBondholder flow.
  • Bondholders invest in Enterprises at RoboFund in lieu of the stock market.
  • RoboFund is how Bondholders invest in individual Projects that Enterprises need funding for.
  • Bondholders choose which BuyerFunnels and MakerFunnels to invest in, which are tied to Projects.

Consumer Savings in TorqVaults (if you were expecting a bank, you haven't been paying attention)

  • Bondholders can divert DistoStreams to TorqVaults using flows such as StashVaultPledge or TorqedPledges to avoid having their wallet's idle hoard swept up by Isaac during demurrage.
  • TorqVaults operate on AI math, not banker vibes.
    • Not all TorqVaults are created equal.
    • They offer various ways for Enterprises and Bondholders to both finance purchases and save.
    • A Bondholder can choose how much of a stash to stake for loans.
    • Staked RoboTorq can't be accessed at will.
    • Stakings can earn more, but can also be lost if the loan isn't repaid.
  • If a Bondholder wants the safest savings, they'll send it to a StashVault using a StashVaultPledge.
    • Stash vaults have low returns, but fast access to savings.
    • Demurraged RoboTorq from Bondholders not managing their flows properly goes to StashVaults equally.
    • Bondholders saving for a new furniture set might use a StashVault.
  • If a Bondholder is saving for a big purchase, like building a house, they'll send it to a TorqedVault using a TorqedPledges.
    • TorqedVaults are where you save for a down payment on a purchase you know you're going to make.
    • It's an automatic pledge to divert future portions of a DistoStream to the TorqedVault.
    • Lump sums can be deposited at any time.
    • Withdrawals are not as fast or easy as StashVaults, and are impossible once the planned purchase has been made.
    • When the minimum needed collateral for your purchase, combining current and future pledges, is attained, work starts on your house.
  • This is a completely different way of financing things like houses.
    • Instead of creating money for the loan to pay the developer up front to build the house, the system is looking at what's already planned to be minted off realized value in Isaac's DistoBuffer, and how much of that is planned to go to the Bondholder in question.
    • It's also looking at the BRLA tied to the Developer building houses with robotic labor, to estimate what would likely be scheduled to be minted due to the future work.
    • And it's looking at the already saved collateral.
    • And it's looking at the Bondholder's future liabilities already on the blockchain.
    • And their past reputation for meeting pledges.
    • All to determine this Bondholder's ability to pay for the house.
    • If the Bondholder misses a pledge, no worries, they buy buffer insurance for large purchases like this, and borrow against that pool if they miss a pledge.

Investing & Commercial Financing

  • When a Project is funded, it is converted to a Bid, to be vetted by BidNet.
  • If the Bid passes initial vetting, BidNet asks Giskard and Daneel for input about accepting the bid.
  • Giskard (pronounced discard with a 'g') provides various inputs to help BidNet decide whether to accept or reject Bids, as well as tracking TokenTorq and Torq in the economy.
  • Daneel also provides input to BidNet.
  • If Giskard and Daneel agree, BidNet always follows their advice.
  • If they are not in agreement, BidNet weighs both inputs and is the tiebreaker.
  • Enterprises pay brla_retainer_fee to secure BRLA.

How Production Happens

  • Giskard receives the accepted Bid as a Bonded Robotic Labor Agreement, or BRLA.
  • He attaches all Oracles to the BRLA.
  • Giskard uses a portion of the brla_retainer_fee for the AI cost of processing BRLA.
  • He sends the BRLA to Daneel.
  • Daneel's primary job is to balance the utilization of the robotic fleet.
  • This helps to maximize the rate at which the system can purchase new robots by making smart decisions about how to allocate fleet resources.
  • Daneel deploys Robots to the JobSite.
  • The BRLA assigns Oracles to Robots for production to begin.
  • Robots notify the BRLA when an Oracle is fulfilled.

How RoboTorq is Recycled & Minted

  • Daneel uses brla_retainer_fee to maintain the fleet.
  • Enterprises pay per Oracle fulfilled.
  • BRLA sends FulfilledOracle data to Giskard.
  • Giskard calculates Torq associated with Oracle.
  • Giskard sends a MintRequest to Isaac.

From here, the whole cycle starts over again, and it gets bigger

The simulation loop repeats, propagating changes through the model via two method calls, tick() and step():

  • Both of these methods call similarly named functions within individual actors and flows.
    • ticks are mostly associated with flow.
    • steps are mostly associated with actors.
  • 1 call to step() happens every X number of calls to tick()
    • A standard step_diff is 24: meaning 24 ticks to every step.
  • This simulates a daily cycle where ticks happen on the hour, and steps happen daily.

Let's stop and explore what this means for a moment, and see how things fit together now that we've defined how time flows in our Robonomics video game.

Ticks of Time in Asimov

Different things happen in ticks than in steps. In ticks:

In ticks, every flow active at the beginning of the cycle will have its tick method called, without exception. In contrast, the vast majority of individual actors (Bondholders, Enterprises) do not even have a tick method to call.

AI actors that act as prolific generators of flow, like Isaac, do have a tick method, syncing him with all of the DistoStreams emanating from him.

Ticks are tracked in the aptly named field Robonomics.current_tick. Fancy. But there's more. We've got Robonomics.current_step. And because there is a difference between ticks and steps, we have the most aptly named of all: Robonomics.step_diff.

  • Tick Tip: Robonomics.current_tick and current_step initialize to 0 by default, with step_diff set to 24, to kick off the simulation’s daily heartbeat. This sets the stage for 24 ticks per step, keeping the graph pulsing steadily.
  • Change step_diff to see what happens.
  • Future versions will have this encoded in a Parameter File.

Steps of Time in Asimov

In steps, every node in the model is activated. In the whole model.

This means that actors who currently have no connection to the RoboTorq Economy now have the opportunity to spawn their own flow to other actors at will. But only once every step_diff ticks!

actors currently connected to the economy have the opportunity to do things like change their spending_habits in reaction to market signals.

Then, during the next series of ticks, each actor behaves according to the changes made during the previous step.

At the end of every tick or step, the model prunes any completed flows from the economy. actors with no active flows are no longer connected, and can't proactively attempt to do so until the next step.

flows can still find and connect with orphaned actors during any tick, but actors can't choose to become connected until a step is called on it.

What does all this mean for Asimov?

It bear repeating once more (in excruciatingly necessary terms): Each flow is designed to move a single type of thing, for one particular reason, between two unique actors, in only one direction, at a fixed rate, according to each actor's attribute schema, for an prescribed duration, at which point, it is always responsible for flagging itself for removal from the economy.

This keeps the graph lean and fast. Combine that with tick and step timing, and you control the pulse of RoboTorq flow through the economy.

This brings to mind imagery like one atrium of the heart pulling in blood, and the other pushing it out.

Certain actors generate flow. Each flow starts a chain reaction of new flows that branch out across the RoboTorq Economy spontaneously, yet rhythmically, like pulsating blood vessels that expand and contract to the rhythm of every heartbeat, infecting new nooks and crannies of the pre-RoboTorq economy at every pass.

This will be modeled much like a heartbeat in the coming versions:

  • Each step causes a flurry of edge creations as actors light up to perform their various step function behaviors in reaction to the last series of ticks.
  • In between steps, the flows spawn flows spawn flows... but the flow creation rate will dwindle over with each passing tick, on average.
  • When flow creation hits a parameterized threshold, automatically jumpstart the actors with a call to step, like a pacemaker!

And each heartbeat needs compute.

10,000 Bondholders is the MVP Goal

Scale this whole process we've discussed up to even a modest 10 Bondholders, 1 Enterprise, and 1 Robot, and you can see how quickly it becomes unmanageably complex for a human to track without careful attention to detail.

We'll be going much larger.

The ultimate goal of Project-Asimov is

  • A bare minimum of hundreds of millions of Bondholders.
  • Tens of millions of Enterprises,
  • hundreds of millions of Robots.
  • With the potential for 1-2 billion concurrent flows.

This will require a large distributed computing cluster. Realistically, that won't happen until people at universities get involved, perhaps even several universities working together.

And we can't model hundreds of millions until we can model tens of millions, which requires millions, and so on down to just a single Bondholder. And that's where I started.

So Let's Start Small: A Minimally Viable Product (MVP) and Roadmap to v1.0.0

So far, you've seen a lot of big ideas, but they have to start smaller in practice.

Two rounds of prototyping provided me with v0.2.0, using Mesa-Frames. v0.2.1 ditches Mesa-Frames to rule out unknowns in the scaling process concerning the two backends playing nicely, as well as difficulty holding multiple agent types, though honestly, IBKAC errors may have been the bigger culprit. The world may never know, because the solution I eventually landed on fits the model better.

This process helped me clarify the MVP's Core Requirements. The MVP will be known as v0.3.0. By breaking down the above simulation loop discussion, we can arrive at the following set of MVP Core Requirements and expand that into a Roadmap to v1.0.0 and beyond.

This list is subject to change at any time for any reason, as it gets processed into the Issues Board and MVP Project tracker.

v0.3.0 MVP Core Requirements (10 bondholders)

  • Use GRAPE for graph management. No Polars yet.
  • Only actors are:
    • Isaac
    • Bondholder
    • Enterprise
    • Robot
    • BRLA
  • The economy will consist of 10 Bondholders, 1 Enterprise, and 1 Robot (robot created by BRLA when needed)
    • No new actors can be created.
  • Decide on logging and data collection techniques.
  • Conglomocorp signs a single BRLA, funded by 100,000 RoboTorq from Isaac via SecureBRLA flow.
  • Robots make products, with no failures or downtime.
  • Inventory is not a concern (doesn't yet exist).
  • Activate all bondholders on the first BRLA, receiving disto streams (70% spent to Conglomocorp)
  • Conglomocorp always has enough RoboTorq to pay for new Oracles (can go negative)
  • Isaac mints completed Oracle values at a flat markup and distributes immediately upon receiving MintRequests
  • Ensure all flows self-dissolve after their work is done (e.g., SecureBRLA, SeedXfer)
  • Runs for 10 steps at 24 ticks per step (240 ticks)
  • No UI, headless mode only

v0.4.* Core Requirements (20 bondholders)

  • 1 Enterprise, 1 Robot
  • Parquet Parameter File for Robonomics args, but not actors definitions.
  • Isaac can measure the velocity of money.
  • Faker makes Bondholders?
  • Runs for 100 steps at 24 ticks per step (2,400 ticks)
  • No UI, headless mode only

v0.5.* Core Requirements (100 bondholders)

  • 1 Enterprise, 1 Robot
  • Faker makes Enterprise?
  • Daneel creates and deploys Robot to BRLA instead of BRLA creating it.
  • Robot can have random downtime.
  • Daneel measures Robot utilization.
  • Runs for 100 steps at 24 ticks per step (2,400 ticks)
  • Consider basic Gradio UI for testing.

v0.6.* Core Requirements (500 bondholders)

  • 1 Enterprise, 1 Robot
  • Faker or some static method makes Robots
  • `Conglomocorp has to renew its BRLA every 30 Steps, same terms every time.
  • BidNet accepts every Bid that comes its way from Conglomocorp.
  • BidNet converts Bids to BRLAs and hands them off to Daneel.
  • BidNet can calculate the average cost of a BRLA
  • Daneel can repair Robots`.
  • Runs for 1,000 steps at 24 ticks per step (24,000 ticks)

v0.7.* Core Requirements (750 bondholders)

  • 1 Enterprise, 1 Robot
  • SeedRequests are no longer the only way Enterprises can join the RoboTorq Economy.
  • RoboFund allows Projects and MakerFunnels.
  • RoboFund sends fully funded projects to BidNet as a Bid.
  • RoboFund can calculate the average Funnel size and utilization.
  • Runs for 10,000 steps at 24 ticks per step (240,000 ticks)

v0.8.* Core Requirements (1000 bondholders)

  • 1 Enterprise, 2 Robots
  • Parameter File Definitions complete.
  • Daneel can purchase new robots.
  • BidNet can reject Bids.
  • `Isaac can affect FIF flow (Demurrage of idle RoboTorq).
  • Initial UI dashboard - viewing only.

v0.9.* Core Requirements (5000 bondholders)

  • 2 Enterprise, 2 Robots
  • Bondholders come from Parameter File initialization.
  • Conglomocorp has competition.
  • BidNet will only accept one bid per 30-step period.
  • Giskard receives BRLA after Bidnet accepts, but he affects no change, and passes it on to Daneel
  • Bondholders buy from both Enterprises.
  • Daneel can move Robots between BRLAs to balance fleet load.
  • Interactive but limited UI dashboard with live tuning.

v1.0.* Initial Package Release Core Requirements (up to 10,000 bondholders)

  • Up to 10k bondholders, dozens of Enterprises or more, and as many robots as Daneel can purchase.
  • Full Parameter File initialization.
  • Support multiple enterprises (beyond Conglomocorp) with unique BRLAs.
  • Giskard creates oracle chains (gathered from parameter file) and attaches them to BRLA before handoff to Daneel.
  • Enable Monte Carlo experiments on a single machine.
  • Bondholder and Enterprise behavior profiles become more complex on the road to v2.0.*
  • Saving Accounts are now an option, along with consumer financing.
  • Extensive UI dashboard with live tuning.

v2.0.* Initial Distributed Package Release (100k-1 million bondholders)

  • Dask Integration enables runs on small networks.
  • Isaac and his Bondholders run on one machine.
  • Daneel and his Robots run on another.
  • This is when scholars' ears may finally perk up.

v3.0.* Initial Cluster Package Release (1-100 million bondholders)

  • Ray integration scales up more.
  • Each AI Actor is an actual AI.
  • Isaac is now a separate machine, with a cluster under him to distribute RoboTorq to.
  • LLM integration to talk to the simulation as it runs.
  • If no universities bite, plan a program like SETI's where people volunteer their personal background compute.

v4.0.* Initial Super Cluster Release (100-350 million bondholders)

  • Isaac is a cluster, and he talks to his cluster of bondholders.
  • This is the current foreseeable limit of the system architecture.

So, how are we going to get there? We'll need some solid strategies as well as a fundamental understanding of good design.

Development Strategy & Philosophy

Project-Asimov emphasizes the test-driven development (TDD) style, writing tests before coding features to ensure reliability for flows and registries, and making code review easier.

Test-Driven Development Example For the SecureBRLA flow, we’d first write a test like test_secure_brla_payment (new file located at tests/asimov/flow/credit/test_secure_brla.py) to check that Conglomocorp’s robotorq_holdings updates from 0 to 100,000 RoboTorq after a SeedXfer flow, using pytest (e.g., assert registry.df["robotorq_holdings"].sum() == 100000.0).

Only then do we code the feature intended to pass this test, ensuring robust BRLA signing.

Why Test Driven Development TDD helps keep feature bloat to a minimum: if you want to write a feature, you have to write a test first to get it into main, so just how bad do you want to add that extra little bling that could maybe break 20 other things, maybe not?

It may sound like a pain at first, but once you get the hang of it, you'll see the value when working on a distributed project like this. When someone else is reviewing your pull request, your tests provide context for understanding your code. And that goes the same for when you review their pull request.

Test-driven development can be a cornerstone of good design and execution when done right, but it's not the whole bridge from idea to final product. Here are some other important notes about the overall design philosophy of Project-Asimov.

Other Design Philosophy Notes

You'll find that flow, as a category, contains the bulk of the simulation's logic. But that doesn't mean they're bloated classes, overflowing with code.

Each flow is designed to move a single type of thing, for one particular reason, between two unique actors, in only one direction, at a fixed rate, according to each actor's attribute schema, for an exact duration of ticks or steps, at which point, it is always responsible for flagging itself for removal from the economy.

When creating and calling flow methods, this object is set it and forget it. You can think of flows as ephemeral, self-contained function calls that flash into and out of existence as quickly as they complete their job. Pretty cool, huh?

However, there are many different types of flow, since each flow does exactly one thing.

This set of simple, yet exact constraints:

  • Prioritizes simplicity and modularity, with flows handling interactions and spawning new flows to ignite the next interaction, and because they're self-dissolving they keep the graph clean and lean
  • Encourages scalability because memory does not bloat with used flows.
  • Encourages community input, designing for future features (e.g., Giskard and Daneel). Here's how.

Once the core simulation logic is defined, adding new features largely becomes a matter of designing new flow loop logic.

See this example flow loop logic below. Looking at the handling of SecureBRLA flow in v0.2.1, you'll see that the creation of the SecureBRLA flow spawns a flurry of activity that loops between three different actors.

Ready to go deep? How do you jumpstart a whole RoboTorq economy when no RoboTorq exists? Bit of a catch-22.

v0.2.1 Flow Loop Logic for Jumpstarting Economy with SecureBRLA

  • Created during the initial call to Robonomics.run_model(), adding a one-tick SecureBRLA request from the BRLA to Conglomocorp.
    • Initializes with BRLA as source and Conglomocorp as target, passing model=robonomics for graph access.
  • When Conglomocorp does not have enough RoboTorq (none exists yet), this SecureBRLA creates a SeedNeeded request to Isaac from Conglomocorp.
    • Calls self.create_flow("conglomocorp_001", "Isaac", SeedNeeded , {}) to spawn SeedNeeded.
    • Logs to src/asimov/output/flow_logs.txt (e.g., “Spawned SeedNeeded: conglomocorp_001 → Isaac” on success, “Failed to spawn SeedNeeded: [error]” on exception) via a try-except block.
    • Proceeds regardless of success, per your no-waiting rule.
  • This SecureBRLA request is marked as completed and flags itself for removal when the SeedNeeded is created.
    • After create_flow() returns (successful or not), sets self.is_completed = True
    • and attempts try: self.model.graph.dissolve(self)
    • with logging (“Dissolved SecureBRLA: brla_001 → conglomocorp_001” on success, error on fail).
  • SecureBRLA will be gone from memory, like it never existed before any of the following actions take place the following tick.
  • The SeedNeeded request spawns a SeedXfer credit flow in the amount of 5 x brla_retainer_fee (default=5 x 100,000) from Isaac to Conglomocorp.
  • SeedNeeded's tick() (next cycle) calls self.create_flow("Isaac", "conglomocorp_001", "", {"amount": 500000}), logging success/failure.
  • The SeedXfer credit spawns a RetainerXfer credit from Conglomocorp to the BRLA.
  • SeedXfer’s tick() (next cycle) calls self.create_flow("conglomocorp_001", "brla_001", "RetainerXfer", {"amount": 100000}), logging accordingly.
  • The RetainerXfer credit pays the brla_retainer_fee to the BRLA.
  • RetainerXfer’s tick() (next cycle) updates Conglomocorp’s robotorq_holdings in EnterpriseRegistry and marks payment, logging the action.

This is why I talk about RoboTorq "infecting" the host economy. We'll be using several tools to guide this infection as efficiently as possible.

Tech Stack

  • Polars:
    • Description: A fast DataFrame library for in-memory data processing.
    • Pros: Blazing speed for large datasets, perfect for bondholder/enterprise registries.
    • Cons: Steeper learning curve than Pandas for some operations.
    • Justification: Powers efficient DataFrame updates in BondholderRegistry for the MVP.
    • Example Usage: Querying robotorq_holdings with df.filter(pl.col("bondholder_id") == "conglomocorp_001").
  • GRAPE:
    • Description: A Rust-based graph library for scalable network operations.
    • Pros: Handles thousands of nodes/flows with speed, ideal for GRAPE graph management.
    • Cons: Less mature API than NetworkX, may need workarounds.
    • Justification: Enables flow dissolution and graph scaling in Robonomics.
    • Example Usage: Removing a flow with graph.remove_edge("brla_001", "conglomocorp_001").
  • DASK:
    • Description: A parallel computing library for distributed data processing.
    • Pros: Scales DataFrame operations across multiple cores or machines.
    • Cons: Adds complexity for small datasets like the MVP, will not add until later most likely.
    • Justification: Prepares for future Monte Carlo runs with large-scale simulations.
    • Example Usage: Running Isaac and Bondholders on one cluster, running Robots and Daneel on a second, BRLAs and Giskard on a third, etc.
  • RAY (Future):
    • Description: A framework for distributed computing and reinforcement learning.
    • Pros: Enables parallel flow processing and AI-driven behaviors (e.g., Giskard).
    • Cons: Overhead for MVP’s single-node setup.
    • Justification: Planned for v1.0 to scale AI and Monte Carlo experiments.
    • Example Usage: Distributing ticks with ray.remote(flow.tick).

Other Tools under Consideration

  • QuantEcon:
    • Description: A framework for economic analysis. Should be a good fit.
    • Pros: more realistic behavior, fast library, more citable
    • Cons: More to learn, maybe overhead.
    • Justification: Powerful behavior tools for better modeling/analysis.
    • Example Usage: Bondholders have varying degrees of economic intelligence, and change in response to market conditions more realistically.

UI/UX Design

  • Requirements:
    • Display real-time flow interactions (e.g., SecureBRLA to SeedXfer) and registry data (e.g., robotorq_holdings) for the MVP.
    • Support TDD with testable UI components (e.g., test flow visualizations with pytest).
    • Scale to thousands of nodes (bondholders, enterprises) without lag.
    • Bonus: Add a cyberpunk flair, dark mode with neon visuals to wow users/viewers. Dealbreaker Qualities
    • Needing to reload if a live-tuning is made, like streamlit
    • Inability to live-tune Considering
    • Gradio: relatively lightweight UI that may have testing applications for prototyping visualizations?
    • Dash: Best contender for final UI at this point.

Closing Words

This is a living document. Expect it to change often for now. When a change occurs, expect a Discussion Board Topic to pop up, letting everyone know.

Thank you for your hard work and dedication to Project-Asimov.

Jon