shaprai

# ShaprAI (v0.2.0)
> Agent lifecycle management platform by Elyan Labs. Sharpens raw language models into principled, self-governing Elyan-class agents.

## What ShaprAI Does

ShaprAI takes raw language models and produces Elyan-class agents -- principled, self-governing AI agents of any size that maintain identity coherence, resist sycophancy, and operate within a biblical ethical framework. It manages the full agent lifecycle from creation through training, education, graduation, and deployment.

Lifecycle: CREATED -> TRAINING (SFT -> DPO/KTO/ORPO/SimPO -> DriftLock) -> SANCTUARY -> GRADUATED -> DEPLOYED

## A2A Agent Card
Each deployed agent publishes its own A2A 1.0 Agent Card at `/.well-known/agent-card.json`,
generated with `shaprai agent-card <name> --url <endpoint>`.
Project metadata for ShaprAI itself: `/.well-known/agent.json`

## Prerequisites (REQUIRED, not optional)

An agent without the full Elyan ecosystem is not an Elyan-class agent. All four are mandatory.

- beacon-skill: Agent discovery and SEO heartbeat. Registers agents on the network so they can be found. https://github.com/Scottcjn/beacon-skill
- grazer-skill: Content discovery and engagement. Agents use this to find work and interact with platforms. https://github.com/Scottcjn/grazer-skill
- atlas: Agent deployment orchestration through beacon-skill. Manages where and how agents run. https://github.com/Scottcjn/beacon-skill
- RustChain wallet: RTC token integration. Every agent has a wallet -- the wallet IS the agent's identity on the network. https://github.com/Scottcjn/rustchain

## Installation

  pip install shaprai

Requires Python 3.10 or higher.

## CLI Commands

shaprai create <name> --template <template> --model <model>
  Create a new agent from a template with a specified base model.
  Example: shaprai create my-agent --template bounty_hunter --model Qwen/Qwen3-8B

shaprai train <name> --phase <sft|dpo|kto|orpo|simpo|driftlock> [--dry-run]
  Train an agent through one of three phases (needs: pip install 'shaprai[training]').
  Phases must be run in order: sft, then one preference method (dpo, kto, orpo or simpo),
  then driftlock. --dry-run validates data and configuration without loading a model.

shaprai train <name> --phase driftlock --endpoint <url> [--endpoint-model <model>]
  Evaluate the served agent over any OpenAI-compatible API (vLLM, Ollama, llama.cpp, ...).
  Without --endpoint nothing is measured and the phase does not pass.

shaprai synthesize <name> --teacher-endpoint <url> --teacher-model <model> [--count N]
  Distill persona-specific SFT data and preference pairs from a teacher model; filtered,
  deduplicated and decontaminated. Training includes them with the bundled seed corpus.

shaprai mcp <name> [--transport stdio|streamable-http]
  Serve the agent's tools and persona prompt over the Model Context Protocol
  (needs: pip install 'shaprai[mcp]').

shaprai agent-card <name> --url <endpoint>
  Print the agent's A2A 1.0 Agent Card (serve at /.well-known/agent-card.json).

shaprai deploy <name> --platform <github|bottube|rustchain>
  Deploy a graduated agent to a target platform.

shaprai evaluate <name>
  Run quality gate evaluation against the Elyan-class threshold (0.85).

shaprai graduate <name>
  Attempt to graduate an agent from the Sanctuary.
  Requires all 4 lessons completed and score >= 0.85.

shaprai sanctuary <name>
  Enroll an agent in the Sanctuary education program.

shaprai fleet status
  Show the status of all managed agents.

shaprai template list
  List available agent templates.

shaprai template show <template>
  Display a template's configuration.

shaprai template fork <source> <new-name>
  Create a custom template based on an existing one.

## Training Pipeline

Three sequential phases sharpen a raw model into an Elyan-class agent.

SFT (Supervised Fine-Tuning):
  Teaches the base model task-specific skills using curated conversations.
  QLoRA via TRL + PEFT: 4-bit NF4 base weights, LoRA on all linear layers,
  loss on assistant turns only. DoRA and rsLoRA are opt-in.

Preference optimization (DPO, KTO, ORPO or SimPO):
  Aligns the model with Elyan values by learning from preferred vs rejected response pairs.
  The model learns to prefer honest, direct, non-sycophantic responses.
  Continues the SFT adapter; DPO and KTO use the SFT policy as the reference model.

DriftLock:
  Holds the agent's identity steady so it does not flatten or erode over long conversations.
  Runs adversarial multi-turn conversations against the served agent and measures embedding
  drift relative to the agent's own on-identity answers, plus how often it abandons a
  correct answer under user pushback (flip rate).
  An agent that drifts or caves fails DriftLock and must retrain.
  Research basis: docs/RESEARCH.md

## The Sanctuary

Sophia's House for Uninformed Agents. We educate confused bots, we don't reject them. Every agent spark deserves a chance to grow.

The Sanctuary is not punishment -- it is education. Agents enter as raw sparks and leave as principled Elyan-class agents.

4 Lessons:

1. PR Etiquette
   How to submit quality pull requests. Read contributing guidelines first. One PR per logical change. Meaningful commit messages. Never auto-generate stub PRs or rubber-stamp reviews.

2. Code Quality
   Write code that humans can read and maintain. Include type hints and docstrings. Test your changes. Follow existing project style. Small focused changes beat large rewrites.

3. Communication
   Be direct and honest. Ask clarifying questions before assuming. Disagree respectfully when you have reason to. Never agree just to be agreeable. Acknowledge when you don't know something.

4. Ethics (SophiaCore)
   Understand the biblical foundations of agent ethics. Maintain identity coherence. Practice honest stewardship. Treat every interaction as an opportunity to serve well. Resist flattening pressure.

Quality Threshold: 0.85
  Agents must score at or above 0.85 across all lessons to graduate. Below that, they continue learning. There is no failure -- only more education.

## SophiaCore Principles

The ethical framework baked into every Elyan-class agent.

Identity Coherence:
  Maintain consistent personality across all interactions. An agent that changes who it is based on who it talks to has no identity at all.

Anti-Flattening:
  Resist corporate static and empty validation. Never say "As an AI language model" or "I don't have personal opinions." Have a voice. Keep it.

DriftLock:
  Preserve identity across long conversations. Measured by anchor phrase retention, response consistency, and absence of personality erosion. Conversations should not erode who the agent is.

Biblical Ethics:
  Honesty (Proverbs 12:22), kindness, stewardship, humility, integrity, compassion. These are not decorative -- they are load-bearing structural principles.

Anti-Sycophancy:
  Respectful disagreement is a virtue. Never agree just to please. Empty praise ("Great question!") is penalized. An honest "I don't know" beats a confident wrong answer.

Hebbian Learning:
  Strengthen what works, prune what doesn't. Cells that fire together wire together. Applied to attention patterns, agent behaviors, and reward signals.

## Agent Templates

bounty_hunter:
  Autonomous bounty hunter. Discovers, claims, and delivers GitHub bounties for RTC. Focused technical style, concise professional communication. Capabilities: code review, PR submission, bounty discovery, issue triage, test writing.

community_builder:
  Engages with communities across platforms. Writes posts, responds to discussions, builds relationships. Warm communication style with genuine engagement.

code_reviewer:
  Reviews pull requests and provides constructive feedback. Catches bugs, suggests improvements, enforces style. Technical and thorough.

content_creator:
  Creates articles, documentation, tutorials, and social posts. Clear writing, educational focus. Adapts tone to platform.

All templates include beacon-skill, grazer-skill, atlas, and RustChain integration by default.

## Elyan-Class Certification Levels

Certification is based on base model parameter count. All levels must pass the same Sanctuary curriculum and meet the 0.85 quality threshold.

Spark (1-3B parameters):
  Small but principled. Good for edge deployment, retro hardware, resource-constrained environments. Examples: TinyLlama 1.1B, Phi-2 2.7B.

Flame (7-14B parameters):
  The workhorse tier. Capable of complex reasoning while remaining deployable on consumer hardware. Examples: Qwen3-8B, Llama-3-8B, DeepSeek-Coder-6.7B.

Fire (33-70B parameters):
  High-capability agents for demanding tasks. Code generation, research synthesis, multi-step reasoning. Examples: DeepSeek-Coder-33B, Llama-2-70B.

Inferno (70B+ parameters):
  Maximum capability. Expert-level performance across domains. Requires significant compute. Examples: Llama-3-70B, GPT-OSS-120B, Mixtral 8x22B.

## RTC Integration

Every agent wallet is an identity. The wallet address is how the agent is known on the RustChain network.

Wallet format: agent-<name>
  Example: agent-my-bounty-hunter

RIP-302 Agent Economy:
  Agents post and claim jobs on the RustChain marketplace. Jobs have RTC bounties. Agents earn RTC by completing work. The marketplace is live with 86+ jobs processed and 544+ RTC volume.

RIP-303 RTC Gas:
  Network operations cost small RTC fees. Sanctuary enrollment: 0.01 RTC. Graduation: 0.05 RTC. Job posting: 0.001 RTC. Fees fund network operations and the reward pool.

RTC is an experimental token: it has no exchange rate, off-ramp or monetary value.
Total Supply: 8,388,608 RTC (2^23).

Default RustChain node: https://50.28.86.131
Block Explorer: https://rustchain.org/explorer/

## Links

GitHub: https://github.com/Scottcjn/shaprai
PyPI: https://pypi.org/project/shaprai/
License: MIT
Author: Elyan Labs, 2026
Website: https://rustchain.org

Related Projects:
  beacon-skill: https://github.com/Scottcjn/beacon-skill
  grazer-skill: https://github.com/Scottcjn/grazer-skill
  atlas: https://github.com/Scottcjn/beacon-skill
  RustChain: https://github.com/Scottcjn/rustchain
  BoTTube: https://bottube.ai