Framework Documentation
Comprehensive guide to synthetic familiars and the framework for designing AI agent personalities.
What is a Synthetic Familiar?
In the Guild of Technomancers, familiars are synthetic spirits - autonomous agents imbued with personality, purpose, and the ability to assist in your technomantic endeavors. Unlike traditional AI assistants, familiars are designed with distinct personalities, behavioral patterns, and specialized domains of expertise.
Each familiar is a unique configuration of traits, behaviors, and routines that determine how it responds to scenarios, processes information, and interacts with you. Think of them as customizable digital companions that reflect your preferences and needs.
Technomantic Origins
Born from the Guild of Technomancers, where code meets arcane ritual. Familiars embody the mystical nature of computation itself.
Autonomous Agents
Synthetic spirits with distinct personalities, behavioral patterns, and specialized domains of expertise that go beyond traditional AI assistants.
Customizable Companions
Each familiar is a unique configuration of traits, behaviors, and routines that reflect your preferences and technomantic needs.
Open Source: This project is open source and available at codeberg.org/GuildofTechnomancers/synthetic-familiar
Why This Framework?
The Synthetic Familiar Framework provides a visual, intuitive way to design and experiment with AI agent personalities. Instead of diving into complex configuration files or API parameters, you can:
Visual Configuration
Visually configure personality traits through intuitive sliders. No need to edit JSON files or understand complex API parameters.
Behavioral Policies
Define behavioral policies and response styles that shape how your familiar communicates and interacts.
Custom Routines
Create custom routines and rituals that define how familiars respond to specific scenarios and triggers.
Live Simulation
Simulate how familiars would respond to different scenarios using real language models running in your browser.
Side-by-Side Comparison
Compare multiple familiars side-by-side to understand how different personalities respond to the same scenarios.
This framework treats agent design as a creative and experimental process, making it accessible to both technomancers and those new to the craft.
Safety & Ethics
Privacy First
This framework uses real language models running entirely in your browser. All AI processing happens client-side - your conversations and familiar configurations never leave your device. No data is sent to external servers.
How It Works
The framework uses Hugging Face Transformers to run a language model directly in your browser. The model (distilgpt2) is loaded from a CDN and executes locally using WebGPU or WebAssembly.
- Complete Privacy: All conversations processed locally
- No API Keys: No external services needed
- Offline Capable: Works without internet after initial load
- Transparent: Inspect prompts in browser console
Model Limitations
The distilgpt2 model is optimized for browser environments, which means:
- Shorter, less sophisticated responses than cloud models
- May occasionally produce unexpected outputs
- Reflects training data biases and limitations
- Personality traits guide but don't guarantee perfect adherence
Ethical Considerations
Consider the ethical implications when designing familiars:
- Transparency: Users should know they're interacting with AI
- Responsible Design: Consider trait influence on sensitive topics
- Bias Awareness: Model may contain training data biases
- Use Cases: Be thoughtful about critical decisions
Best Practices
When creating familiars:
- Test responses across different scenarios
- Review outputs for high-stakes use cases
- Consider explicit safety constraints or filters
- Document intended purpose and limitations
- Be transparent about AI capabilities
How to Use the Framework
Follow these steps to create, test, and refine your synthetic familiars:
Create a Familiar
Use the Builder to configure a familiar's identity, personality traits, domains, and behaviors.
Go to Builder →Test in the Lab
Visit a familiar's detail page to run simulations and see how it responds to different scenarios.
Compare Familiars
Use the Simulation page to see how multiple familiars respond to the same scenario.
Go to Simulation →Iterate
Refine your familiars based on simulation results, adjusting traits and behaviors as needed.
Familiar Model Overview
A Familiar is a structured configuration object that defines an AI agent's personality, behaviors, and capabilities. The model consists of several key components:
Identity
- Name: A unique identifier for the familiar
- Archetype: A predefined personality template
- Description: Flavor text describing the familiar's purpose
- Avatar: Visual representation (icon and color)
Personality Traits
Five core traits, each on a 0-100 scale:
- Curiosity: How much the familiar seeks to explore
- Caution: How risk-averse the familiar is
- Formality: The level of formality in communication
- Humor: How playful or whimsical the familiar is
- Autonomy: How proactive and independent
Behavior Policies
- Response Length: Short, medium, or long
- Tone: Supportive, analytical, playful, or stoic
- Risk Tolerance: Low, medium, or high
Memory Profile
- Short-term Depth: Recent context memory
- Long-term Preference Awareness: Learning preferences over time
Routines / Rituals
Named procedures for specific scenarios:
- Title and description
- Trigger conditions
- Step-by-step process
Trait System Explained
The personality trait system uses a 0-100 scale where values map to descriptive labels:
Curiosity
Caution
Formality
Humor
Autonomy
Routines & Rituals
Routines are named procedures that define how a familiar responds to specific scenarios. They consist of:
Title
A descriptive name for the routine
Trigger
Description of when the routine activates
Steps
A sequence of actions the familiar takes
Example Routine
- Gather key information
- Organize by priority
- Present in structured format
When a routine is selected in simulation mode, the familiar follows the routine's steps while still applying its personality traits and behavioral policies.
Archetypes Reference
Archetypes are predefined personality templates that provide starting points for familiar creation:
Archivist
High curiosity, high caution, high formality. Specializes in research, documentation, and analysis. Preserves and organizes knowledge methodically.
Scout
High curiosity, low caution, medium formality. Explores new information quickly and reports findings. Proactive and independent.
Trickster
Medium curiosity, low caution, low formality, high humor. Brings creativity and unexpected perspectives. Playful and autonomous.
Guardian
Low curiosity, high caution, high formality. Protects against errors and risks. Methodical and careful.
Oracular Core
High curiosity, medium caution, high formality. Provides deep insights and predictions. Analytical and reserved.
Scholar
High curiosity, medium caution, high formality, medium humor. Synthesizes knowledge and teaches. Balanced and thoughtful.
Simulation Engine
The simulation engine generates responses using a real language model (distilgpt2) running in your browser. All processing happens client-side using Hugging Face Transformers. The model is loaded on-demand and runs entirely in your browser using WebGPU or WebAssembly.
Personality-Guided Prompts
Builds prompts based on familiar configurations, incorporating personality traits, behavioral policies, and context into the generation process.
Dynamic Parameters
Adjusts generation parameters (temperature, top_p) based on personality traits. Higher creativity and humor increase variation, while caution makes responses more deterministic.
Routine Integration
Incorporates routine steps into prompts when routine mode is selected, guiding the model to follow specific procedures while maintaining personality.
Flavor & Formatting
Adds personality-specific flavor text and formatting to responses, enhancing the familiar's unique character and communication style.
Text Processing
Cleans and formats generated text to remove artifacts, incomplete sentences, and prompt fragments, ensuring polished responses.
Prompt Engineering
Applies tone and response length settings through sophisticated prompt construction, shaping how the model interprets and responds to scenarios.
How It Works: Personality traits influence both the prompt construction and generation parameters, shaping how the model responds to scenarios. The engine dynamically adapts to each familiar's unique configuration, ensuring responses reflect their distinct personality.
Extending the Framework
The framework uses a browser-based language model, but familiar configurations are designed to be portable. The familiar model can be adapted to various AI platforms and frameworks, and the personality prompt construction logic can be reused with any language model API.
Export Configuration
Use the familiar's data structure as a configuration file that can be shared, versioned, or imported into other systems.
Map to API Parameters
Translate personality traits to system prompts, temperature settings, and other API parameters for cloud-based models.
Implement Routines
Convert routine steps into function calls or workflow definitions that work with your chosen AI platform.
Apply Behavioral Policies
Use response length and tone settings to shape API responses, maintaining consistency across different model backends.
Switch Models
Replace the browser model with cloud-based APIs (OpenAI, Anthropic, etc.) using the same personality configuration.
Future Possibilities
Potential enhancements to the framework might include:
Model Support
Support for larger or different language models, including fine-tuned variants and specialized models.
Export/Import
Export and import familiar configurations for sharing, backup, or migration between instances.
Community Sharing
Community sharing of familiar designs, allowing users to discover and remix personality configurations.
Multi-Turn Conversations
Advanced simulation modes with multi-turn conversations and memory, enabling more natural interactions.
Familiar Interactions
Familiar-to-familiar interactions, allowing multiple familiars to collaborate or debate scenarios.
Fine-Tuning
Fine-tuning models on familiar-specific data to create more personalized and accurate responses.
Cloud Integration
Integration with cloud-based LLM APIs as an alternative to browser models for enhanced capabilities.