Social Network Simulation Framework

A framework for simulating dynamic social networks.

Features

• Agent-based simulation with customizable behaviors
• Directed graph representation of social networks
• Flexible feed algorithm system
• Comprehensive logging and visualization
• Support for different agent types

Project Structure

• src/: Source code for the simulation framework
  • agent/: Agent implementations
  • network/: Network, database, and feed algorithm components
  • models/: Data models and type definitions
  • simulation/: Simulation orchestration and logging
  • visualization/: Visualization utilities
• tests/: Test cases
• notebooks/: Jupyter notebooks with examples
• data/: Output directory for simulation results

Installation

Clone the repository and install dependencies

git clone https://github.com/conflictednerd/social-agents.git
cd social-agents
pip install -e .

Quick Start

Here's a simple example to get started:

from src.agent.random_agent import RandomAgent
from src.network.social_network import SocialNetwork
from src.network.content_database import ContentDatabase
from src.network.feed_algorithm import BasicFeedAlgorithm
from src.simulation.simulation import Simulation

# Create components
network = SocialNetwork()
content_db = ContentDatabase()

# Add some agents
for i in range(10):
    agent = RandomAgent(agent_id=i, engagement_rate=0.5)
    network.add_agent(agent)

# Create feed algorithm
feed_algorithm = BasicFeedAlgorithm(
    social_network=network,
    content_database=content_db
)

# Create simulation
simulation = Simulation(
    social_network=network,
    content_database=content_db,
    feed_algorithm=feed_algorithm
)

# Run the simulation
simulation.run(num_steps=100)

See the notebooks/demo.ipynb for a more comprehensive example.

LLM Agent Usage

1. Install your LLM client

pip install llama-cpp-python
# or openai, anthropic, etc.

2. Create & run an LLMAgent

from llama_cpp import Llama           # or your preferred client
from src.agent.llm_agent import LLMAgent
from src.network.social_network import SocialNetwork
from src.network.content_database import ContentDatabase
from src.network.feed_algorithm import BasicFeedAlgorithm
from src.simulation.simulation import Simulation

# initialize your LLM 
llm = Llama(
    model_path="path/to/your/model.gguf",
    n_ctx=2048,
    temperature=0.7
)

# build your sim components 
network    = SocialNetwork()
content_db = ContentDatabase()
feed_algo  = BasicFeedAlgorithm(network, content_db)

# create 3 LLM‑driven agents 
for i in range(3):
    agent = LLMAgent(
        llm=llm,
        agent_id=i,
        engagement_rate=1.0
    )
    network.add_agent(agent)

# run the sim 
sim = Simulation(
    social_network   = network,
    content_database = content_db,
    feed_algorithm   = feed_algo
)
sim.run(num_steps=100)

3. What happens under the hood?

• Each tick, LLMAgent.get_feed(...) builds a small batch of messages for your LLM:
  • A system message framing the agent’s personality
  • A user message containing its memory, recent feed items, and the instruction to both draft a post and decide follow/unfollow
• You send that batch off via your LLM’s chat_batch(...) (or equivalent) API.
• The LLM returns a JSON blob like:

{
  "post": "My new post content",
  "actions": [
    { "author_id": 5, "action": "follow" },
    { "author_id": 2, "action": "unfollow" }
  ]
}

• LLMAgent.get_llm_completion(...) parses that JSON into an AgentResponse and updates its internal memory.

4. Some more notes

• get_feed(...) returns the messages you pass into your LLM.
• get_llm_completion(...) expects the LLM reply to contain a single JSON object with keys
• "post" → your new post string
• "actions" → a list of {author_id, action} entries
• Swap in whatever batch‑call your provider uses (OpenAI’s create_chat_completion(..., messages=[…]), Anthropic’s SDK, etc.).

Extending the Framework

Creating Custom Agents

Create a new agent class that inherits from the base Agent class:

from src.agent.agent import Agent
from src.models.data_models import FeedItem, AgentResponse

class MyCustomAgent(Agent):
    def __init__(self, agent_id, engagement_rate, **kwargs):
        super().__init__(agent_id, engagement_rate)
        # Initialize additional parameters
        
    def update(self, feed: List[FeedItem]) -> AgentResponse:
        # Process feed and generate response
        return AgentResponse(
            new_posts=["My new post content"],
            follow_actions=[42],  # Agent IDs to follow
            unfollow_actions=[7]  # Agent IDs to unfollow
        )

Creating Custom Feed Algorithms

Create a new algorithm class that inherits from the base FeedAlgorithm class:

from src.network.feed_algorithm import FeedAlgorithm
from src.models.data_models import FeedItem

class MyCustomFeedAlgorithm(FeedAlgorithm):
    def __init__(self, social_network, content_database, **kwargs):
        self.social_network = social_network
        self.content_database = content_database
        # Initialize additional parameters
        
    def generate_feed(self, agent_id: int, max_items: int = 10) -> List[FeedItem]:
        # Generate personalized feed for the agent
        # ...
        return feed_items