metadata

title: Florentine Families Graph
emoji: 🌍
colorFrom: indigo
colorTo: blue
sdk: gradio
sdk_version: 5.12.0
app_file: app.py
pinned: false
license: cc-by-sa-4.0

Here’s a compelling README for your application:

Florentine Families Network Analysis

Welcome to the Florentine Families Network Analysis Tool

a simple yet powerful prototype designed to analyze the Florentine family network using graph-based metrics.
integrates Smolagents, Arize Phoenix, and NetworkX to explore the relationships and centrality dynamics of Renaissance-era Florence families.
the app.py code is a little out of date but I left it as is as it showcased where effective telemetry can bring immediate visibility to the impact of minor changes in the tool definition

NOTE: Smolagents has some cool features like reusable tools - but as expected there are some growing pains

Key Features

1. Smolagents for Agentic Intelligence

Employs Smolagents to power agentic workflows with multi-step reasoning and secure code execution.
Uses the CodeAgent to execute Python-based tool calls, enabling dynamic interactions with graph data.
Integrates tools like centrality calculators and visualization functions, allowing users to explore the network effectively.

2. NetworkX for Graph Analysis

Leverages the Florentine Families dataset from NetworkX, a classic representation of Renaissance family alliances.
Computes critical centrality metrics such as:
- Degree Centrality: Identifies the most connected families.
- Betweenness Centrality: Highlights families bridging other relationships.
- Closeness Centrality: Finds families with optimal influence in the network.
Provides visual insights into the network structure, helping uncover pivotal roles in Florence's social fabric.

3. Arize Phoenix for Telemetry and Debugging

Integrates with Arize Phoenix via OpenTelemetry, ensuring robust tracking and inspection of agent workflows.
Logs agent actions, tool calls, and errors, enabling users to debug and optimize their queries.
Supports analysis of user interactions and system performance through intuitive dashboards.

4. Interactive Gradio Interface

Provides a user-friendly interface for inputting queries and viewing results.
Predefined examples guide users to explore the centrality roles of key families like the Medici and Strozzi.
Displays results in textual and visual formats for enhanced comprehension.

How It Works

Input Your Query: Use natural language to describe your analysis goals (e.g., "Highlight the Medici family's role using betweenness centrality.").
Agentic Reasoning: The CodeAgent formulates the necessary computations and retrieves insights using NetworkX and predefined tools.
Graph Analysis: Metrics are computed and analyzed in real-time, with visualizations optionally generated using tools like PyVis.
Telemetry Monitoring: Every interaction is logged and monitored via Arize Phoenix, providing transparency and debugging capabilities.

Examples

Analyze Medici's Central Role

"Highlight the Medici family's central role in the network using all three centrality metrics."

Explore the Strozzi Family

"Focus on the Strozzi family's role in the network using betweenness centrality."

Compare Families

"Compare family positions in the network using degree and closeness centrality."

Overview of 6 CodeAgent runs

Code Generated to create HTML

html-output

Setup Instructions

Prerequisites

Python 3.8 or higher
Hugging Face API Token (HF_TOKEN)
Arize Phoenix API Key (PHOENIX_API_KEY)

Installation

Clone this repository.
Install dependencies:
```
pip install -r requirements.txt
```

Export environment variables:

export HF_TOKEN=your_hf_api_token
export PHOENIX_API_KEY=your_phoenix_api_key

Run the app:
```
python app.py
```

Technology Stack

Smolagents: For agentic workflows and secure execution.
NetworkX: For robust graph-based computations.
Arize Phoenix: For monitoring and telemetry via OpenTelemetry.
Gradio: For an intuitive user interface.
PyVis: For interactive graph visualizations.

Contributing

We welcome contributions! Please submit issues or pull requests for enhancements or bug fixes.

License

This project is licensed under cc-by-sa-4.0.

Acknowledgments

Smolagents by Hugging Face
NetworkX for their graph library and Florentine family dataset
Arize Phoenix for telemetry insights that accelerated the alignment of LLM behavior