personagent 1.0.0__tar.gz

personagent-1.0.0/.env.example

@@ -0,0 +1,423 @@
+# personagent settings. `personagent init` fills in the first block for you.
+# Each setting is described on the lines above it; a blank value means the
+# default the description gives.
+
+# ============================================================================
+# REQUIRED
+# ============================================================================
+
+# The chat model: any OpenAI-compatible service, hosted or local (Ollama).
+# The key is all that `personagent chat` needs.
+LLM_API_KEY=
+# The API address as the provider documents it: a root such as
+# https://api.deepseek.com, a version base such as .../v1 or .../api/paas/v4,
+# or the full /chat/completions URL.
+LLM_BASE_URL=https://api.deepseek.com
+LLM_MODEL=deepseek-flash
+
+# The bot's name. It notices being addressed when a message contains it.
+PERSONA_NAME=
+
+# Language of the agent: en or zh. Picks the bundled examples, feedback,
+# lorebook and output filters (data/*.en.* or data/*.zh.*), the reply checks
+# and the words its commands understand. It does not translate your persona.
+AGENT_LANG=en
+
+# ============================================================================
+# PERSONA AND ACCESS
+# ============================================================================
+
+# The persona document, and its optional companion card, both relative to
+# AGENT_HOME. Until persona.txt exists, the bundled
+# data/persona.example.<lang>.txt stands in.
+# The card holds per-persona reply-style opt-ins, such as
+# {"reply_style": {"emoji": true, "charsets": ["music"], "max_chars": 320}};
+# charsets are ellipsis, music and arrows. Without a card no emoji and no
+# optional characters are allowed. A `[style]` block at the end of the persona
+# document sets the six register knobs: length, vent, recs, good_news,
+# particles and fatigue.
+PERSONA_FILE=persona.txt
+PERSONA_CARD_FILE=persona.card.json
+
+# The persona's time zone as a UTC offset in hours, from -12 to 14, such as
+# 8 or -5. It sets the time shown to the model and the 02:00-07:00 sleep
+# window, when the bot does not start conversations. Blank = UTC+8 when
+# AGENT_LANG is zh, this machine's offset otherwise.
+PERSONA_TZ_OFFSET_HOURS=
+
+# A label recorded on every evidence event beside a hash of the persona text.
+# Editing the persona keeps what the bot learned: every version under one
+# label counts as the same character (runtime/persona_lineage.json). Change
+# the label to start a new character with a clean slate.
+PERSONA_VERSION=
+
+# Ids are written "<platform>:<id>", the platform spelled as the connector
+# names it (AstrBot's adapter names: telegram, discord, slack, kook, lark, ...),
+# such as telegram:-1001234567 or discord:4242. A bare id, or qq:<id>, is a
+# QQ number. None of these is needed for `personagent chat`.
+
+# The admin: the one person who runs the bot, with an account on as many
+# platforms as you list. The bot is closest to them, they may manage what it
+# remembers about a group, and they may teach it on their own.
+ADMIN_IDS=
+ADMIN_NAME=
+# How the bot relates to the admin, such as brother, boss or friend.
+# Blank = not mentioned in prompts.
+ADMIN_RELATIONSHIP=
+
+# The groups the bot answers, and who besides the admin may DM it. Each
+# platform is gated on its own. A platform with no entries here is not
+# restricted by the agent: every QQ group is answered, a QQ DM needs the admin
+# or an entry, and any other platform is left to the connector's allowlist
+# (such as the AstrBot plugin's groups and dm_users). One entry for a platform
+# restricts that platform to its entries. DM users get the "ordinary friend"
+# persona: looser than in a group, but not the admin's.
+ACCESS_GROUPS=
+ACCESS_DM_USERS=
+
+# ============================================================================
+# CONNECTORS (the AstrBot plugin, Satori, Matrix)
+# ============================================================================
+
+# POST /v1/events takes messages forwarded from chat platforms and returns the
+# replies in its response (docs/connectors.md).
+# CONNECTOR_TOKEN is the secret the connector signs each request with: a bearer
+# header plus HMAC-SHA256(timestamp + "." + nonce + "." + exact JSON body),
+# checked against replays. Blank is accepted only on loopback; forwarding from
+# another host needs HTTPS (or a private tunnel ending on loopback) and a token.
+# `personagent connect astrbot` writes the same token on both sides.
+CONNECTOR_TOKEN=
+# Events whose sent_at is older than this many seconds are refused even inside
+# a fresh request, which allows an adapter's delayed delivery for up to 24 h.
+CONNECTOR_MAX_EVENT_AGE_S=86400
+# Connector platforms whose ids arrive bare instead of "<platform>:<id>".
+# Set it to the connector's QQ adapter (AstrBot calls it aiocqhttp) to run QQ
+# through a connector: QQ ids then stay plain numbers, the way NapCat and every
+# store on disk spell them. Leave it blank otherwise.
+# Naming a platform here lets its connector address QQ conversations, because
+# bare ids are what the QQ entries of ADMIN_IDS, ACCESS_GROUPS and
+# ACCESS_DM_USERS are compared against. Only QQ's adapter belongs here.
+CONNECTOR_QQ_PLATFORMS=
+# Messages nobody asked for (openers, the follow-up question after a rejection,
+# the excuse when the model call fails) reach a forwarded platform only through
+# a connector that polls POST /v1/outbox and says so ("capabilities":
+# ["outbox"], see docs/connectors.md). false turns the outbox off: the endpoint
+# answers 404, and such messages go out on QQ through NapCat only.
+CONNECTOR_OUTBOX_ENABLED=true
+# Connector turns run at the same time. /v1/events holds a slot for a whole
+# turn, so it has its own budget. Blank = QQ_ONEBOT_MAX_INFLIGHT.
+CONNECTOR_MAX_INFLIGHT=
+
+# ============================================================================
+# SERVICE AND STORAGE
+# ============================================================================
+
+# Where personagent listens. Loopback by default (blank too), so nothing is
+# exposed. A split deployment may set SERVER_HOST=0.0.0.0, but then startup
+# requires CONNECTOR_TOKEN, and /v1/onebot is off unless QQ_ONEBOT_SECRET is set.
+SERVER_HOST=127.0.0.1
+SERVER_PORT=8080
+# The web page at http://127.0.0.1:<SERVER_PORT>/: status, why it spoke or
+# stayed quiet, and what it learned, with promote / reject / roll back. It
+# opens only through its private link (the token in runtime/dashboard.token),
+# which `personagent run` and `personagent doctor` print. false leaves it out.
+DASHBOARD_ENABLED=true
+# The largest request body either endpoint accepts, in bytes.
+SERVER_MAX_BODY_BYTES=8000000
+# Logs go to the console. A path here also writes rotating log files, which can
+# contain conversation details; keep it outside the repository or gitignored.
+SERVER_LOG_FILE=
+
+# The deployment folder: .env, persona.txt, runtime/ and the instance lock are
+# resolved under it. Blank = this checkout, or the folder `personagent init`
+# set up (~/personagent by default). AGENT_RUNTIME_DIR must stay beneath it.
+# Set it to run several personas from one installed copy.
+AGENT_HOME=
+
+# Everything the bot learns or remembers (memory, evaluations, ledgers,
+# learned pools, sticker notes) is written here, never into data/. Relative
+# paths are under AGENT_HOME. runtime/ is gitignored; another folder inside a
+# repository needs the same, because it holds real conversations.
+AGENT_RUNTIME_DIR=runtime
+
+# false keeps the service up but the agent answers nothing.
+AGENT_ENABLED=true
+
+# ============================================================================
+# OPTIONAL FEATURES (safe to leave as they are)
+# ============================================================================
+
+# --- Model calls ---
+# Per-request timeout in seconds, and retries after a transient error.
+LLM_TIMEOUT_S=120
+LLM_MAX_RETRIES=2
+# Another model name for DMs, served by the same endpoint and key as LLM_MODEL.
+# The exception: a name equal to LLM_FALLBACK_MODEL is served where the
+# fallback is. Blank = LLM_MODEL.
+LLM_DM_MODEL=
+# The cheap first step when the bot speaks on its own (judging whether to join
+# in, follow-ups, openers) asks this model only "reply or stay quiet?". The
+# line that is sent is written by the main model. Blank = LLM_FALLBACK_MODEL,
+# else the main model. Point it at the cheapest model you have.
+LLM_JUDGE_MODEL=
+
+# --- Fallback when busy (a cheaper model while the main one is loaded) ---
+LLM_FALLBACK_MODEL=
+# The fallback model's own endpoint, so an outage at the main provider is not
+# also the fallback's. Blank = LLM_BASE_URL and LLM_API_KEY. Only a
+# LLM_FALLBACK_MODEL different from LLM_MODEL is sent here, together with the
+# judge, self-eval and reaction calls whose models default to it. A blank key
+# with a URL on another provider sends LLM_API_KEY there, so give it its own.
+# Accepts the same spellings as LLM_BASE_URL.
+LLM_FALLBACK_BASE_URL=
+LLM_FALLBACK_API_KEY=
+# DeepSeek's `thinking` field turns hidden reasoning off for the judge, the
+# search decision and the sticker tagger. DeepSeek, Zhipu, Moonshot and
+# Volcengine hosts get it; OpenAI, Groq, Gemini, OpenRouter, Mistral and
+# Anthropic do not; any other endpoint is asked on its first such call, and
+# the answer is kept per model. true = send it to the fallback's host without
+# asking. An endpoint that answers 400 to it is not sent it again.
+LLM_FALLBACK_THINKING=false
+# When LLM_RATE_THRESHOLD calls fall within LLM_RATE_WINDOW_S seconds, the
+# next LLM_FALLBACK_DURATION_S seconds use the fallback model.
+LLM_RATE_WINDOW_S=120
+LLM_RATE_THRESHOLD=30
+LLM_FALLBACK_DURATION_S=180
+# Seconds a model that answered 429 (rate limited) is skipped. Shorter than
+# LLM_FALLBACK_DURATION_S because a throttled model is metered, not broken.
+# Any other failure (a 400, retries used up) keeps the model out for
+# LLM_FALLBACK_DURATION_S.
+LLM_RATE_LIMIT_COOLDOWN_S=20
+
+# --- Conversation ---
+# Messages from others before the bot considers joining in unasked.
+CHAT_TRIGGER_COUNT=30
+# Messages of history kept per conversation for the prompt.
+CHAT_CONTEXT_MESSAGES=120
+# Seconds after the bot's reply during which new messages count as follow-ups.
+CHAT_FOLLOWUP_WINDOW_S=120
+# The notes file under AGENT_RUNTIME_DIR, and how many notes each
+# conversation keeps.
+MEMORY_FILE=memory.json
+MEMORY_MAX_PER_CONVERSATION=50
+
+# --- Web search (looks up unfamiliar things) ---
+# With a Tavily key it uses Tavily (more reliable); blank uses DuckDuckGo,
+# which needs no key (the `ddgs` package from requirements.txt).
+TAVILY_API_KEY=
+
+# --- Vision (images and stickers) ---
+# Blank = no vision model, only OCR, which costs nothing. Any OpenAI-compatible
+# vision model works; give it its provider's key and base URL here, since there
+# is no default endpoint.
+VISION_MODEL=
+VISION_API_KEY=
+VISION_BASE_URL=
+# The largest decoded image accepted from base64, a file or HTTP, in bytes.
+VISION_MAX_IMAGE_BYTES=5000000
+
+# --- Self-eval (scores each reply 1-5 into eval.jsonl, in the background) ---
+# Off by default, so a first run costs least. Prefer a model from another
+# vendor than the chat model: a model family is blind to its own failure
+# modes. An EVAL_MODEL containing "moonshot" or "kimi" goes to the vision
+# endpoint above.
+EVAL_ENABLED=false
+EVAL_MODEL=
+EVAL_FILE=eval.jsonl
+
+# --- Proactive messages (the bot sometimes speaks first) ---
+# Off by default. When on, a background loop may start a conversation after a
+# chat has been quiet for a while (outside the sleep window), with cooldowns
+# and a low chance, and the model is told to stay quiet unless it has
+# something to say. Groups and DMs, but only people and groups the bot has
+# seen talk since it started. On QQ it sends through NapCat, and DMs go only to
+# the QQ ids in ADMIN_IDS and ACCESS_DM_USERS. Elsewhere it needs a connector
+# that pulls the outbox (CONNECTOR_OUTBOX_ENABLED), and DMs go to anyone that
+# connector lets through.
+PROACTIVE_ENABLED=false
+# Platforms it may speak first on, comma-separated (qq, telegram, discord,
+# ...); blank = every platform it can reach.
+PROACTIVE_PLATFORMS=
+# How often the loop checks, in seconds (25 min).
+PROACTIVE_INTERVAL_S=1500
+# A group must be quiet this long first, in seconds (45 min).
+PROACTIVE_MIN_SILENCE_S=2700
+# Least time between openers in one group, in seconds (3 h).
+PROACTIVE_COOLDOWN_S=10800
+# Chance per eligible check, 0 to 1.
+PROACTIVE_PROB=0.25
+# A DM must be quiet this long first, in seconds (4 h).
+PROACTIVE_DM_MIN_SILENCE_S=14400
+# Least time between DMs to one person, in seconds (24 h).
+PROACTIVE_DM_COOLDOWN_S=86400
+# Chance per eligible check for a DM, 0 to 1.
+PROACTIVE_DM_PROB=0.2
+
+# --- Learning from reactions ---
+# On by default. Each reply waits a while for a reaction aimed at it: a quote
+# of the bot's message, a mention or its name, or in a DM the other person's
+# next message. One cheap model call reads the reaction as a correction,
+# rejection, positive or neutral, and filters out banter and trolling.
+# A reaction is recorded as evidence (append-only, in
+# runtime/evidence.<lang>.jsonl) and may propose a candidate. A candidate
+# changes nothing until it is promoted (next block). Every reading is also
+# logged in candidates.jsonl (src=user_reaction).
+REACT_LEARN_ENABLED=true
+# How long a reply waits for a reaction, in seconds (15 min).
+REACT_TTL_S=900
+# Replies tracked per conversation.
+REACT_MAX_PENDING=4
+# The model that reads reactions. Blank = LLM_JUDGE_MODEL (the cheapest
+# configured).
+REACT_MODEL=
+# After a rejection, how long the bot's next reply still counts as its second
+# try, in seconds.
+REACT_FIX_WINDOW_S=600
+# After an accepted rejection, the bot may later ask what the person meant
+# (delayed, with a cooldown).
+REACT_ELICIT_ENABLED=true
+# Seconds to wait before asking, so it never talks over its own reply to the
+# rejection.
+REACT_ELICIT_DELAY_S=120
+# Least time between such questions in one conversation, in seconds.
+REACT_ELICIT_COOLDOWN_S=3600
+
+# --- Promotion (when learned material may change replies) ---
+# A reaction is evidence, and reading it creates a candidate. Promotion gives a
+# candidate a say in future replies; a rollback or a newer candidate takes it
+# away. Only promoted candidates are used, through
+# runtime/promoted.{examples,feedback}.<lang>.jsonl, a view rebuilt from the
+# append-only ledger and never edited by hand.
+# The defaults make one thing impossible: a single automatic signal changing
+# for good how the bot talks. Loosen them only while watching the results.
+# Review what is waiting with `personagent learned list`.
+#
+# Strong = an explicit correction with a concrete better line, from the person
+#          the reply was meant for, or a second try that person accepted.
+# Weaker = a rejection with nothing concrete, a correction from a bystander,
+#          or the bot's own review. Real evidence, not a mandate.
+# Weak   = laughter, agreement, banter, the bot's own score. Never promotes
+#          anything on its own, so good examples are promoted by you.
+# Being the admin does not stand in for being the person the reply was for,
+# and conflicting evidence blocks automatic promotion.
+#
+# false = nothing is promoted without you.
+PROMOTE_AUTO_ENABLED=true
+# Distinct agreeing events needed (at least 2).
+PROMOTE_MIN_EVENTS=2
+# Of which this many must be strong (at least 1).
+PROMOTE_MIN_STRONG=1
+# From this many different people (at least 1). One person can supply both
+# events, by correcting a reply and then accepting the retry; an honest
+# clarification looks exactly like misuse of it. 2 stops a stranger from
+# teaching the bot alone in a room: the admin is exempt, and a candidate held
+# back this way still waits for you to approve.
+PROMOTE_MIN_SPEAKERS=1
+# Evidence older than this many days stops counting; 0 = no limit.
+PROMOTE_EVIDENCE_MAX_AGE_DAYS=30
+# Never combine evidence from different conversations.
+PROMOTE_REQUIRE_SAME_CONVERSATION=true
+
+# --- Size of the learned pools ---
+# Each reply picks 4 examples and 6 better-reply pairs from the read-only data/
+# seeds, the learned runtime/ pools and the promoted views. These caps bound
+# the machine-written part: they size the promoted views, and the offline
+# tools apply them to what they write. Older material came from an older
+# prompt, and without a cap it outvotes the recent. Raise them for very varied
+# topics; 0 = no cap. What you wrote or approved yourself is never counted or
+# dropped.
+PROMOTE_MAX_EXAMPLES=500
+PROMOTE_MAX_FEEDBACK=500
+
+# --- Self-improvement loop (from self-eval scores to candidates) ---
+# Off by default. When on, a background loop takes new low scores from
+# eval.jsonl, has a model diagnose each and draft a better reply, and files it
+# as a candidate. Nothing is applied: a self-diagnosis is one signal nobody
+# witnessed, so it waits for a real reaction to agree, or for you to promote it.
+# The same with a review step: python tools/auto_reviewer.py --apply
+# Needs EVAL_ENABLED=true.
+EVOLVE_AUTO_ENABLED=false
+# Hours between looks at new scores.
+EVOLVE_INTERVAL_HOURS=6
+# A score at or below this counts as a miss (3 = drifting into an assistant's
+# voice, the band this loop is for).
+EVOLVE_THRESHOLD=3
+# Most entries diagnosed per round.
+EVOLVE_BATCH=5
+# Blank = EVAL_MODEL, else the chat model.
+EVOLVE_MODEL=
+
+# --- Retrieval by meaning (embeddings) ---
+# Retrieval ranks examples, pairs and notes on the words they share with the
+# message (BM25), where they were learned (this conversation, then this
+# persona, then the shipped seeds) and how recent they are. An embedding model
+# adds meaning: a row that says the same thing in other words can win.
+# Blank EMBEDDING_MODEL = off. Any OpenAI-compatible /embeddings endpoint
+# works (OpenAI, SiliconFlow, Zhipu, a local Ollama). Vectors are cached in
+# AGENT_RUNTIME_DIR/embeddings.jsonl. A reply waits at most 3 seconds for its
+# message to be embedded; a slow or failing endpoint is logged once, and
+# retrieval ranks without it until it answers.
+EMBEDDING_MODEL=
+# Blank = LLM_BASE_URL with LLM_API_KEY. A URL of its own gets only
+# EMBEDDING_API_KEY (blank for an endpoint that needs no key). Accepts a root,
+# a version base (/v1, /api/paas/v4) or the full /embeddings URL.
+EMBEDDING_BASE_URL=
+EMBEDDING_API_KEY=
+
+# --- Offline tools (not read by the running bot) ---
+# Listed so the startup check knows these names are real settings.
+# tools/prompt_lab.py writes through a different vendor than the agent under
+# test, which makes it a measurement rather than a mirror. Needs
+# `pip install -e ".[judge]"`.
+ANTHROPIC_API_KEY=
+ANTHROPIC_BASE_URL=
+# Required by the lab: a model the vendor above serves.
+LAB_MODEL=
+# tools/auto_reviewer.py; blank = EVAL_MODEL, else the chat model.
+REVIEWER_MODEL=
+# The scoring model of `personagent eval` (persona and learning suites) and
+# tools/evolution_benchmark.py --judge, again from another vendor than the one
+# measured. BENCH_JUDGE_BASE_URL and BENCH_JUDGE_API_KEY default to
+# LLM_BASE_URL and LLM_API_KEY.
+BENCH_JUDGE_MODEL=
+BENCH_JUDGE_API_KEY=
+BENCH_JUDGE_BASE_URL=
+BENCH_EVAL_DELAY_S=
+
+# --- Ledger size warnings ---
+# The evidence log and the candidate ledger are append-only and never shrink.
+# These are the sizes, in bytes, at which each starts warning in the log; they
+# do not cap or rotate anything.
+LEDGER_EVIDENCE_WARN_BYTES=
+LEDGER_CANDIDATES_WARN_BYTES=
+
+# ============================================================================
+# QQ THROUGH NAPCAT (OneBot v11)
+# ============================================================================
+
+# QQ comes in through AstrBot (CONNECTOR_QQ_PLATFORMS above). The direct
+# OneBot route, NapCat posting to /v1/onebot, is deprecated and still served.
+# Which QQ groups the bot answers is ACCESS_GROUPS.
+
+# The bot account's QQ number, on either route.
+QQ_BOT_ID=
+
+# NapCat's HTTP server, such as http://127.0.0.1:3000. On the direct route
+# every reply goes out through it; through AstrBot it is only used for
+# proactive sends and the sweep for mentions missed while the bot was busy.
+# Blank = not used. Events never come this way; they reach SERVER_PORT.
+QQ_ONEBOT_URL=
+
+# If NapCat hands over received images as file:// paths (its local-cache
+# mode), set this to that cache folder. Blank refuses every file:// path.
+QQ_ONEBOT_IMAGE_DIR=
+
+# The `secret` in NapCat's HTTP client config. Read only by the direct route:
+# with it set, each /v1/onebot body must carry a matching
+# `x-signature: sha1=<hex>` header. Blank accepts only programs on this
+# machine, and nothing at all when SERVER_HOST is not loopback.
+QQ_ONEBOT_SECRET=
+
+# Expensive OneBot requests handled at the same time. Requests beyond this get
+# HTTP 429 instead of piling up memory and model calls.
+QQ_ONEBOT_MAX_INFLIGHT=64

personagent-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Qiankang (Kant) Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

personagent-1.0.0/MANIFEST.in

@@ -0,0 +1,7 @@
+# What setup.py bundles into the wheel, so a wheel built from the sdist has it too.
+include requirements.txt .env.example
+graft data
+graft integrations/astrbot/astrbot_plugin_personagent
+# The sdist builds the package; the test suite runs from a checkout.
+prune tests
+global-exclude *.py[cod]