from dotenv import load_dotenv
load_dotenv()Trueapi
Interaction with Flock.io’s API
The Flock API reference can be found here.
Tasks
In most cases you will want to get single task information to work with.
get_task
get_task (task_id:int, as_df:bool=False)
Get task as JSON or Dataframe.
task_info = get_task(1, as_df=False)
task_info{'title': 'Foundation Model for Web3 Agent',
'description': 'The Web3 world is buzzing about AI agents, but true decentralization can’t happen if every agent relies on GPT or Claude. FLock is rallying open-source and decentralized AI engineers to build a foundation model with robust function-calling capabilities for blockchain-related tasks. Together, let’s empower everyone to create their own models and agents.',
'task_type': 'training',
'data': {'training_set_url': 'https://fed-ledger-prod-dataset.s3.amazonaws.com/1/training_set.jsonl?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASSFQ745NLT5K57N2%2F20250410%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Date=20250410T130858Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=6565638731440c5bc264fff1c7b3598bbc88b984ce86c815799227f3bf296f3f',
'max_params': 9500000000,
'context_length': 4096},
'duration_in_seconds': 2160000,
'id': 1,
'status': 'finalized',
'initialized_at': '2024-12-31T03:02:33.260306',
'submission_phase_ends_at': '2025-01-25T23:59:59.260306',
'final_validation_ends_at': '2025-01-30T23:59:59.260306',
'final_link': 'https://huggingface.co/jfranklin-foundry/task-1-microsoft-Phi-3-mini-4k-instruct'}test_eq(task_info["id"], 1)
test_eq(task_info["task_type"], "training")
test_eq(task_info["title"], "Foundation Model for Web3 Agent")task_df = get_task(1, as_df=True)
task_df| title | description | task_type | duration_in_seconds | id | status | initialized_at | submission_phase_ends_at | final_validation_ends_at | final_link | data_training_set_url | data_max_params | data_context_length | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | Foundation Model for Web3 Agent | The Web3 world is buzzing about AI agents, but... | training | 2160000 | 1 | finalized | 2024-12-31T03:02:33.260306 | 2025-01-25T23:59:59.260306 | 2025-01-30T23:59:59.260306 | https://huggingface.co/jfranklin-foundry/task-... | https://fed-ledger-prod-dataset.s3.amazonaws.c... | 9500000000 | 4096 |
test_eq(task_df["id"].item(), task_info["id"])
test_eq(task_df["task_type"].item(), task_info["task_type"])We are most interesting in tasks that are in the submission phase.
open_tasks
open_tasks (as_df:bool=False)
open_task_df = open_tasks(as_df=True)
open_task_df| title | description | task_type | duration_in_seconds | id | status | initialized_at | submission_phase_ends_at | final_validation_ends_at | data_recommended_vram | data_dataset_s3_key | data_max_params | data_context_length | data_training_set_key | data_validation_set_key | data_final_validation_set_key | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | FLock x OneKey: Advancing AI-Driven Smart Cont... | FLock and OneKey are collaborating to launch t... | training | 2419200 | 7 | submission_phase | 2025-03-26T16:22:01.791348 | 2025-04-23T23:59:59.791348 | 2025-04-28T23:59:59.791348 | 48GB | onekey-security/combined.jsonl | 15000000000 | 8192 | 7/training_set.jsonl | 7/validation_set.jsonl | 7/final_validation_set.jsonl |
assert not open_task_df.emptyfinalized_tasks
finalized_tasks (as_df:bool=False)
fin_tasks = finalized_tasks(as_df=True)
fin_tasks.tail(3)| title | description | task_type | duration_in_seconds | id | status | initialized_at | submission_phase_ends_at | final_validation_ends_at | data_dataset_s3_key | data_max_params | data_context_length | data_training_set_key | data_validation_set_key | data_final_validation_set_key | data_recommended_vram | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 4 | AI Hedge Fund: QuantumApex | QuantumApex will function as a key component o... | training | 1296000 | 3 | finalized | 2025-01-30T15:46:35.932388 | 2025-02-14T23:59:59.932388 | 2025-02-19T23:59:59.932388 | hedge_fund/combined.jsonl | 8000000000 | 4096 | 3/training_set.jsonl | 3/validation_set.jsonl | 3/final_validation_set.jsonl | 24GB |
| 5 | AI Producer: SEEK48 | <p>FLock introduces SEEK48, an advanced AI ido... | training | 2419200 | 6 | finalized | 2025-03-02T23:02:16.975240 | 2025-03-30T23:59:59.975240 | 2025-04-04T23:59:59.975240 | ai-idol/combined.jsonl | 8000000000 | 4096 | 6/training_set.jsonl | 6/validation_set.jsonl | 6/final_validation_set.jsonl | 24GB |
| 6 | Chasm x FLock: AI Mystery | <p>FLock & Chasm introduces an AI-powered meta... | training | 2419200 | 5 | finalized | 2025-02-21T16:55:52.751560 | 2025-03-21T23:59:59.751560 | 2025-03-26T23:59:59.751560 | ai-mystery/combined.jsonl | 8000000000 | 2048 | 5/training_set.jsonl | 5/validation_set.jsonl | 5/final_validation_set.jsonl | 24GB |
assert not fin_tasks.emptySubmission Scores
To view submission scores you will need to set a valid FLOCK_API_KEY in your environment. I suggest using python-dotenv.
get_subs
get_subs (task_id:int, as_df:bool=False)
Get submissions as JSON or Dataframe.
sub_df = get_subs(7, as_df=True)
sub_df.T| 0 | 1 | |
|---|---|---|
| link | https://huggingface.co/clepelaars/task-7-Qwen-... | https://huggingface.co/clepelaars/task-7-Qwen-... |
| submission_phase_score | None | None |
| final_validation_score | None | None |
| submitted_at | 2025-04-10T13:05:58.502101 | 2025-03-28T12:45:21.402671 |
assert not sub_df.emptyStats
The Flock API provides several global and wallet-based stats.
Global stats
The most meaningful global stats are the submission and validation counts per day.
sub_stats
sub_stats (as_df:bool)
Submissions and validation counts per day.
Submission counts as a DataFrame
subs = sub_stats(as_df=True)
subs.tail(3)| time | count | |
|---|---|---|
| 100 | 2025-04-08 | 28 |
| 101 | 2025-04-09 | 39 |
| 102 | 2025-04-10 | 35 |
assert not subs.emptyValidation counts as a DataFrame
def val_stats(as_df: bool):
""" Validation counts per day. """
j = urljson(f'{BASE_URL}stats/emissions?type=validation')['data']
return pd_parse(j) if as_df else jval = val_stats(as_df=True)
val.tail(3)| time | count | |
|---|---|---|
| 100 | 2025-04-08 | 1874 |
| 101 | 2025-04-09 | 2521 |
| 102 | 2025-04-10 | 2306 |
assert not val.emptyWallet-based stats
Most statistics are based on individual addresses. This includes: - Get submissions for a particular wallet - Get achievements of a particular wallet - Retrieve in which tasks a wallet is enrolled (i.e. staked).
FlockWalletStats
FlockWalletStats (address:str)
Get wallet-based stats.
example_wallet = "0xB93A9c73751Bbca8E1924954271ee8d4De5747c9"
fwl = FlockWalletStats(example_wallet)
fwlFlockWalletStats(address='0xB93A9c73751Bbca8E1924954271ee8d4De5747c9', base_url='https://fed-ledger-prod.flock.io/api/v1/stats/')test_eq(fwl.address, example_wallet)We can now retrieve the valid submissions of the wallet as JSON or a DataFrame.
fwl.subs(as_df=False){'items': [], 'total': 0, 'page': 1, 'size': 50, 'pages': 0}m = fwl.subs(as_df=True)
m| items | total | page | size | pages | |
|---|---|---|---|---|---|
| 0 | [] | 0 | 1 | 50 | 0 |
assert not m.emptyValidation achievements
val_achievements = fwl.achievements(as_df=True, role='validator')
val_achievements| gold_medals | silver_medals | bronze_medals | total_participations | tasks | |
|---|---|---|---|---|---|
| 0 | 0 | 0 | 0 | 0 | [] |
assert not val_achievements.empty
expected_cols = ["gold_medals", "silver_medals", "bronze_medals", "total_participations", "tasks"]
test_eq(val_achievements.columns.tolist(), expected_cols)Node achievements
node_achievements = fwl.achievements(as_df=True, role='node')
node_achievements| gold_medals | silver_medals | bronze_medals | total_participations | tasks | |
|---|---|---|---|---|---|
| 0 | 0 | 0 | 0 | 0 | [] |
assert not node_achievements.empty
test_eq(node_achievements.columns.tolist(), expected_cols)HuggingFace
A general requirement for participating in Flock tasks is to upload models to the HuggingFace Hub. For this you will need a HuggingFace token with write access and set the HF_TOKEN environment variable. For setting environment variables I would recommend using python-dotenv.
upload_to_hf
upload_to_hf (repo_name:str, output_dir:str='outputs')
Upload a model to the HuggingFace Hub. :param repo_name: the name of the repository to upload to. For example: myhfname/task-1-model. :param output_dir: the directory to upload to the HuggingFace Hub. :return: the commit hash you will need to submit to Flock.
Submitting to Task
Once you have the HuggingFace model uploaded and retrieved the commit hash, you can submit your results to the Flock task.
submit_task
submit_task (task_id:int, hg_repo_id:str, base_model:str, commit_hash:str)
Submit results to Flock task. :param task_id: the ID of the task you want to submit to. :param hg_repo_id: the ID of the HuggingFace repository you want to submit. :param base_model: the base model you want to use. Must be a valid model name like “Qwen/Qwen1.5-7B or google/gemma-7b. :param commit_hash: the HuggingFace Hub Model commit hash of the model you want to submit.