PsyAgent

Personality-grounded language-model agents for structured social contexts

Created by Zibin Meng and Kani Chen

[Project page] [Manuscript preprint on arXiv]

Important

PsyAgent is a public research repository accompanying a paper accepted to the EMNLP 2026 Main Conference. The camera-ready version is in preparation, and the proceedings version is forthcoming. HKUST-FintechLab/PsyAgent is the authoritative canonical repository. The Mengzibin/PsyAgent repository is a read-only personal mirror. Synchronization is one-way from the canonical repository to the personal mirror.

Repository checks establish engineering properties of the checked-out tree only. They do not independently reproduce the reported results or validate scientific claims, safety, or fitness for use. The acceptance status recorded here is conference metadata, not an inference from those checks.

Overview

PsyAgent is an ongoing research codebase for studying how a Big Five trait profile and a structured social context can condition language-model behavior. It includes persona-like JSON records, supervised fine-tuning (SFT) code, rule-based preference-pair generation and Direct Preference Optimization (DPO) code, and an experimental trait-fidelity evaluation runner based on IPIP-NEO-120-style responses.

The repository is organized as follows:

• dataset/ contains 1,982 persona JSON files subject to the handling terms in dataset/README.md.
• codesft/ contains persona-conditioned SFT and QLoRA code.
• codedpo/ contains seeded, rule-based DPO-pair generation and DPO/QLoRA code.
• wopsyagent/ contains experimental persona and trait-fidelity evaluation code, including a modified FastChat-derived subtree.
• images/ contains project figures, including the framework image subject to THIRD_PARTY_NOTICES.md.

Read dataset/README.md, THIRD_PARTY_NOTICES.md, and REPRODUCIBILITY.md before using these materials.

Project status

Field	Current state
Repository visibility	Public
Manuscript status	Accepted to the EMNLP 2026 Main Conference; camera-ready in preparation; proceedings forthcoming
Canonical repository	HKUST-FintechLab/PsyAgent
Personal repository	Mengzibin/PsyAgent, read-only mirror
Synchronization	Lab canonical to read-only personal mirror only
Included results	None identified
Included checkpoints	None identified
Exact external model revisions	Not pinned
Normalization experiments	No full training or evaluation run

Claim boundary

The normalization smoke check validates required files, size limits, Python and shell syntax, JSON parsing, and selected data schemas. It does not import model code, download models, run training or inference, calculate reported metrics, validate psychological constructs, reproduce manuscript results, or establish the paper's acceptance status. The recorded acceptance status comes from the conference decision. This snapshot cannot presently support a complete, independently auditable scientific reproduction claim because results, checkpoints, and exact model revisions are not included.

Quick start

Clone the public canonical repository and separately obtain authorization for any gated external models. From the repository root, run the CPU-only normalization smoke check:

python3 -B scripts/repository_smoke.py

Requirements are Python 3.9 or newer and Bash on PATH; the smoke command has no third-party Python dependency. A successful run prints a line beginning with [PASS] and exits with status 0. Runtime varies with storage and hardware.

This command does not import project modules or start a GPU workload. Component environment files are reference environment snapshots; review platform-specific CUDA and package constraints before creating an environment.

GPU usage through Slurm only

Training and evaluation are GPU workloads and must be submitted with Slurm sbatch. The legacy scripts under component bash/ directories are retained only for provenance and exit without starting work. Review your cluster's partition, account, GPU, time, model, dataset, and output settings before submission.

SFT examples:

cd codesft
sbatch --partition=YOUR_PARTITION --gres=gpu:1 sbatch/run_sft_llama3_2_1B
sbatch --partition=YOUR_PARTITION --gres=gpu:1 sbatch/run_sft_llama3_2_3B

Generate DPO pairs on CPU, then submit DPO with explicit SFT policy and reference paths:

cd codedpo
python3 scripts/make_dpo_from_sft.py \
  --sft_dir ../dataset \
  --out_dir dpo_pairs \
  --val_ratio 0.05 \
  --seed 42 \
  --max_prompt_length 1024 \
  --max_target_length 1024 \
  --tokenizer_or_path meta-llama/Llama-3.2-1B-Instruct

POLICY_FROM=/approved/path/to/sft-output \
REFERENCE_FROM=/approved/path/to/reference \
sbatch --partition=YOUR_PARTITION --gres=gpu:1 \
  sbatch/run_dpo_llama3_2_1B_q1

Generated DPO JSONL files are deliberately not stored in the latest tree; see codedpo/dpo_pairs/README.md.

Access conditions

• Original PsyAgent software is available under Apache-2.0. The synthetic dataset, project-original documentation, and images/framework.png are available under CC BY 4.0. Third-party materials retain their own terms; the benchmark payloads whose redistribution rights were unclear are excluded. See LICENSE, dataset/LICENSE, and THIRD_PARTY_NOTICES.md for scope.
• Base models are not included. Users must independently satisfy the model provider's access terms and record the exact model ID and revision used.
• API credentials and access tokens must be supplied through approved runtime mechanisms. Never commit them, place them in documentation, or print them in logs. Do not pass credentials through --extra or EXTRA_JSON.

Component-specific details are in codesft/README.md, codedpo/README.md, and wopsyagent/README.md.

Limitations and responsible use

• No full GPU experiment was run during repository normalization.
• Static and schema checks do not establish correctness, reproducibility, validity, reliability, fairness, privacy, or fitness for a use case.
• Dataset content is described as synthetic by the project materials and maintainer, but that description is not an independent privacy guarantee.
• Persona-like or name-like text must not be treated as a verified real person or as proof of de-identification without separate provenance evidence.
• Model outputs may be inaccurate, biased, harmful, or privacy-sensitive.
• Do not attempt re-identification or use this project for diagnosis, treatment, eligibility, employment, education, credit, insurance, policing, or other high-impact decisions.
• Human review and applicable institutional, ethical, privacy, data, model, and third-party license requirements remain necessary.
• Public repository visibility does not itself grant reuse or redistribution rights beyond the applicable license and material-specific terms.

Rights and citation

Original PsyAgent software is licensed under the Apache License 2.0. The synthetic persona dataset, project-original documentation, and images/framework.png are licensed under CC BY 4.0. Third-party material retains its own terms as recorded in THIRD_PARTY_NOTICES.md; the public release does not include the benchmark payloads identified there. Dataset provenance, schema, attribution, and responsible-use guidance are in dataset/README.md.

Citation metadata is available in CITATION.cff. The arXiv record identifies the preprint. The paper has been accepted to the EMNLP 2026 Main Conference; its camera-ready version is in preparation and its proceedings record is forthcoming.