Architectual Notes

The JuliaOS framework follows a client-server architecture with a modular design. The Julia backend (julia/julia_server.jl) runs as an HTTP server (default port 8052), handling core computations with a restructured architecture that provides clear separation of concerns. TypeScript/JavaScript clients, primarily the interactive CLI (scripts/interactive.cjs), connect to this server. The CLI utilizes framework packages (packages/framework, etc.) which in turn use the packages/julia-bridge to communicate with the backend server.

Computation (swarms, blockchain logic, AI calls) happens in the Julia modules (julia/src/*), which interact with external services (RPC nodes, Arweave, Wormhole, OpenAI). The system also provides a Python wrapper (packages/python-wrapper) that offers a comprehensive interface to JuliaOS with support for LangChain, multiple LLM providers, and Google ADK. The modular architecture allows for easy extension and integration with existing components.

Architecture

JuliaOS follows a client-server architecture with a modular design and clear separation of concerns:

Root Directory
├── julia/                 # Core Julia backend server
│   ├── src/               # Julia source code with modular architecture
│   │   ├── core/          # Core modules (Types, Errors, Utils, Config)
│   │   ├── agents/        # Agent management and specialization
│   │   ├── swarms/        # Swarm algorithms and optimization
│   │   ├── blockchain/    # Multi-chain blockchain interactions
│   │   ├── dex/           # DEX operations and price quotes
│   │   ├── bridge/        # Communication bridge with Wormhole integration
│   │   ├── storage/       # Local and decentralized storage (Arweave)
│   │   ├── python/        # Python bridge for wrapper integration
│   │   └── api/           # HTTP API server and endpoints
│   ├── julia_server.jl    # Main HTTP server (port 8052) with full functionality
│   ├── config.jl          # Configuration with environment variable support
│   └── Project.toml       # Julia dependencies
│
├── packages/              # TypeScript/JavaScript packages (monorepo)
│   ├── framework/         # Framework modules mirroring Julia backend
│   │   ├── swarms/        # Swarm algorithms and optimization
│   │   └── ...            # Other framework modules
│   ├── julia-bridge/      # Communication bridge to Julia backend
│   ├── wallets/           # Wallet integrations (MetaMask, Phantom, Rabby)
│   ├── bridges/           # Cross-chain bridge implementations (Wormhole)
│   ├── storage/           # Storage implementations (Arweave)
│   └── python-wrapper/    # Python interface with LangChain, LLM, ADK integrations
│
├── scripts/               # Utility scripts
│   └── interactive.cjs    # Main interactive CLI entry point (Node.js)
│
├── .env                   # Local environment variables (API Keys, RPC URLs) - *Not committed*
├── README.md              # This file
└── ...                    # Config, Docker files, Gitignore etc.

Key Architecture Points

1. Modular Design: Clear separation of concerns with modular architecture for easy extension and maintenance.

2. Client-Server Model: Julia backend server (port 8052), TS/JS frontend/CLI client, Python wrapper.

3. Julia Backend (/julia): Computational engine with real implementations of agents, swarms, blockchain, DEX, storage, and bridges.

4. TypeScript Frontend (/packages, /scripts): User interface (CLI), framework wrappers, blockchain/wallet interaction.

5. Python Wrapper (/packages/python-wrapper): Comprehensive Python interface with LangChain, LLM, and ADK integrations.

6. Framework Structure (/packages/framework): TypeScript interfaces and wrappers for programmatic interaction with the Julia backend.

7. Communication Flow:

   User -> CLI/Python -> Framework -> Bridge -> Network -> Julia Server -> Julia Modules -> External Services

For a detailed architecture overview, see the README files in each package:
- [Framework README](./packages/framework/README.md)
- [Julia Bridge README](./packages/julia-bridge/README.md)
- [Core README](./packages/core/README.md)

For more examples, see the README files in each module:
- [Agents Module](./packages/framework/agents/README.md)
- [Swarms Module](./packages/framework/swarms/README.md)
- [Blockchain Module](./packages/framework/blockchain/README.md)
- [Wallet Module](./packages/framework/wallet/README.md)
- [Bridge Module](./packages/framework/bridge/README.md)
- [Utils Module](./packages/framework/utils/README.md)

## Framework Components

### Julia Backend (`julia/src/`)

The Julia backend provides high-performance modules with real implementations for all components:

```julia
# Example usage of the restructured Julia backend
using JuliaOS.Agents
using JuliaOS.Swarms
using JuliaOS.Blockchain
using JuliaOS.Storage
using JuliaOS.Bridge

# Create an agent
agent = Agents.create_agent(
 "TradingAgent",
 "trading",
 Dict("risk_tolerance" => "medium", "max_position_size" => 1000)
)

# Create a swarm
swarm = Swarms.create_swarm(
 "OptimizationSwarm",
 "DE",
 Dict("population_size" => 50, "crossover_rate" => 0.8, "mutation_factor" => 0.5)
)

# Run optimization
result = Swarms.run_optimization(
 swarm["id"],
 "function(x) return sum(x.^2) end",
 [],  # constraints
 Dict("bounds" => [(-10, 10), (-10, 10), (-10, 10)], "max_iterations" => 100)
)

# Get blockchain balance
balance = Blockchain.get_balance("0x123...", "ethereum")
println("ETH Balance: $balance")

# Store data
document = Storage.save_document("agents", agent)

# Bridge tokens
bridge_result = Bridge.WormholeBridge.bridge_tokens(
 "ethereum",
 "solana",
 "0xUSDC...",
 "100",
 Dict("recipient" => "solana_address")
)

The Julia backend consists of modules within julia/src/, including:

1. Agents: Manages AI agents with different types and specializations.

2. Swarms: Implements multiple swarm intelligence algorithms with constraint handling and adaptive parameter tuning.

3. Blockchain: Interacts with multiple blockchain networks (Ethereum, Polygon, Solana).

4. DEX: Handles DEX interactions with price quotes and slippage protection.

5. Storage: Provides local (SQLite) and decentralized (Arweave) storage.

6. Bridge: Handles communication and cross-chain token transfers via Wormhole.

7. Utils: Provides utility functions for validation, logging, and error handling.

8. Config: Manages configuration with environment variable overrides.

TypeScript Framework (packages/framework)

The TypeScript framework provides interfaces and wrappers for the Julia backend:

// Example usage of the TypeScript framework
import { JuliaBridge } from '@juliaos/julia-bridge';
import { Agents, Swarms, Blockchain } from '@juliaos/framework';

// Initialize the bridge
const bridge = new JuliaBridge({ host: 'localhost', port: 8052 });
await bridge.initialize();

// Create framework modules
const agents = new Agents(bridge);
const swarms = new Swarms(bridge);
const blockchain = new Blockchain(bridge);

// Create an agent
const agent = await agents.createAgent({
  name: 'TradingAgent',
  type: 'trading',
  config: { risk_tolerance: 'medium', max_position_size: 1000 }
});

// Create a swarm
const swarm = await swarms.createSwarm({
  name: 'OptimizationSwarm',
  algorithm: 'DE',
  config: { population_size: 50, crossover_rate: 0.8, mutation_factor: 0.5 }
});

// Run optimization
const result = await swarms.runOptimization({
  swarmId: swarm.id,
  objectiveFunction: 'function(x) return sum(x.^2) end',
  parameters: {
    bounds: [[-10, 10], [-10, 10], [-10, 10]],
    maxIterations: 100
  }
});

// Get blockchain balance
const balance = await blockchain.getBalance({
  address: '0x123...',
  chain: 'ethereum'
});
console.log(`ETH Balance: ${balance}`);

Python Wrapper (packages/python-wrapper)

The Python wrapper provides a comprehensive interface to JuliaOS:

# Example usage of the Python wrapper
from juliaos import JuliaOS
from juliaos.llm import OpenAIProvider
from juliaos.langchain import JuliaOSToolkit

# Initialize JuliaOS
juliaos_client = JuliaOS(host="localhost", port=8052)

# Create an agent
agent = juliaos_client.agents.create_agent(
    name="TradingAgent",
    agent_type="trading",
    config={"risk_tolerance": "medium", "max_position_size": 1000}
)

# Create a swarm
swarm = juliaos_client.swarms.create_swarm(
    name="OptimizationSwarm",
    algorithm="DE",
    config={"population_size": 50, "crossover_rate": 0.8, "mutation_factor": 0.5}
)

# Run optimization
result = juliaos_client.swarms.run_optimization(
    swarm_id=swarm["id"],
    objective_function="function(x) return sum(x.^2) end",
    parameters={
        "bounds": [(-10, 10), (-10, 10), (-10, 10)],
        "max_iterations": 100
    }
)

# Create an LLM provider
llm = OpenAIProvider(api_key="your_openai_api_key")

# Create a LangChain toolkit
toolkit = JuliaOSToolkit(juliaos_client)

# Use the toolkit with LangChain
from langchain.agents import initialize_agent, AgentType
agent = initialize_agent(
    tools=toolkit.get_tools(),
    llm=llm.get_llm(),
    agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
    verbose=True
)

# Run the agent
agent.run("Create a swarm using the DE algorithm and optimize a simple function.")