Welcome to Pippin — a flexible, open-source framework to create a digital “being” that:
- Learns about your goals/objectives and your character’s persona.
- Connects to various tools or APIs (via API keys or OAuth flows through Composio) to perform tasks.
- Dynamically creates and tests new “Activities” in pursuit of your objectives.
- Manages a memory system to track past actions and outcomes.
- Provides a web UI for easy onboarding/config, or a CLI wizard if you prefer terminal workflows.
- Overview
- Features & Highlights
- Prerequisites
- Folder Structure
- Quick Start
- Fork & Clone
- Install Dependencies
- Onboarding & Configuration
- Launch the Agent
- Onboarding Flow: CLI vs. Web UI
- Core Steps (Same Under the Hood)
- LLM Setup
- Objectives & Character
- Adding Skills via Composio or API Keys
- Multiple LLM Model Support
- Default Activities
- Using the Web UI
- Configuring Your Character & Constraints
- Connecting Tools via OAuth (Composio)
- Launching and Monitoring the Agent
- Using the CLI
- Re-running the Onboarding Wizard
- Starting the Agent from Terminal
- Creating a New Skill for Solana-AgentKit (Manual Example)
- Why Keep the AI/Web UI Default?
- Extending & Creating Other Custom Activities
- Memory, State & Activity Selection
- Stopping or Pausing the Agent
- Contributing
- License
This project is designed to help you quickly spin up a self-improving, LLM-driven digital being that:
- Asks you for your objectives and character details.
- Integrates with tools to perform real-world tasks (e.g., tweeting, deploying tokens on Solana, generating images, or web scraping).
- Runs a continuous or scheduled loop, picking or creating new Activities to meet your goals.
- Stores logs in memory (short-term and long-term).
- Adapts by rewriting or generating Python code for new Activities on the fly!
You can choose to run everything from your terminal or via a web-based UI. Both flows do the same underlying initialization—so pick whichever is more comfortable.
-
Flexible Onboarding:
- CLI Wizard or Web UI flow to gather essential info—no duplication of effort.
- Prevents you from starting until you’ve provided at least one LLM API key (or local config) and a minimal character setup.
-
Multiple LLM Model Support:
- Provide one or more LLM API keys (OpenAI, GPT4All, or your custom provider).
- Assign different models to tasks like code generation vs. daily analysis vs. activity selection.
-
Composio:
- OAuth-based gateway to 250+ tools (Twitter, Slack, Google, etc.).
- Built-in flows for quickly adding new “skills” from connected apps.
-
Custom Skills:
- Easily add your own skill, e.g., solana-agent-kit, stable diffusion, or a Node.js microservice.
- The default configuration can help you add manual API keys for tools not using Composio.
-
Default Activities:
- Activities for analyzing daily logs, brainstorming new Activities, generating .py files.
-
Configurable Constraints:
- E.g., “No more than 5 tweets per hour,” “Don’t create new tokens more than once a month.”
-
Memory System & State Tracking:
- The being “remembers” past actions, can reflect on them, and updates its own state (energy, mood, etc.).
- Python 3.9+ recommended.
- A GitHub account (to fork).
- A Composio developer key (optional but recommended) if you want to do OAuth-based skill connections.
.
├─ activities/
│ ├─ activity_daily_thought.py
│ ├─ activity_suggest_new_activities.py
│ ├─ activity_build_or_update.py
│ └─ ... # More built-in or dynamically generated
├─ skills/
│ ├─ skill_lite_llm.py # For local or remote LLM usage
│ ├─ skill_chat.py # Example: OpenAI Chat
│ ├─ skill_solana_agent.py # We'll create this manually (example)
│ ├─ skill_x_api.py # For API skills
| └─ skill_web_scraping.py # Used for scraping information from the web
|
├─ framework/
│ ├─ main.py # Core DigitalBeing class, run loop
│ ├─ activity_selector.py # Hybrid LLM + deterministic selection
│ ├─ memory.py # Short/long-term memory handling
│ ├─ state.py # Tracks energy, mood, etc.
│ ├─ shared_data.py # Thread-safe data for cross-activity usage
│ └─ ...
├─ config/
│ ├─ character_config.json # Where your being's name/personality go
│ ├─ activity_constraints.json # Rate-limits, skill requirements, cooldowns
│ ├─ skills_config.json # Enabled skills + required API keys
│ └─ ...
├─ server/
│ ├─ server.py # Web UI + WebSocket server
│ └─ static/ # HTML/CSS/JS for the front-end
├─ tools/
│ └─ onboard.py # CLI-based onboarding wizard
├─ requirements.txt
├─ __init__.py
├─ server.py
└─ README.md # This document
Fork this repo on GitHub.
Clone your fork:
git clone https://github.com/<your-username>/pippin-draft.git
cd pippin-draft2. Install Dependencies (this step can be skipped if you use GitHub codespaces or the provided dev container)
First, install the UV package manager if not already installed:
curl -LsSf https://astral.sh/uv/install.sh | shThen create and activate your virtual environment:
# Create and activate virtual environment
uv venv
source .venv/bin/activate # On Unix/MacOS
# OR
.venv\Scripts\activate # On WindowsInstall the project dependencies:
uv pip install -r requirements.txtNavigate to the project directory:
cd my_digital_beingCopy the config_sample folder.
cp -r config_sample configYou can pick one of the following approaches:
- CLI:
python -m tools.onboard - Web UI:
python -m serverthen openhttp://localhost:8000in your browser and follow the onboarding prompts.
Either way, you’ll be guided through:
- Choosing your main LLM provider and providing at least one API key (or local model path).
- Defining your character’s name, personality, objectives, constraints, etc.
- Optionally connecting Composio or manually entering API keys for additional skills.
- Ensuring at least one skill is fully configured so you can start the agent.
- CLI:
python -m framework.main - Web UI: Once onboarding is complete, a Start button appears—click to run the main loop.
Both flows rely on shared logic that checks whether:
- You have a named character and objectives.
- At least one LLM skill is configured.
- (Optional) Composio or other skill credentials if you want advanced features.
If these conditions aren’t met, the agent cannot start. This ensures no half-configured usage.
Choose one or more models. Examples:
- GPT4All for code generation
- GPT-3.5 for quick queries
- GPT-4 for reasoning
Provide the necessary API keys or local model paths. If using local GPT4All or other offline LLMs, the system can handle that, too.
Specify:
- Name: e.g., “Optimus Mentis”
- Personality: e.g., “Helpful, curious, somewhat playful”
- Objectives: e.g., primary mission, secondary goals
- Constraints: e.g., “Do not create new tokens more than once a month”
(Stored in character_config.json and activity_constraints.json.)
Composio is recommended if you want your being to do things like:
- Post on Twitter, Slack, or Gmail without manually handling each OAuth.
- Auto-fetch each app’s actions as “dynamic skills.”
API Keys are also possible for tools that either don’t integrate with Composio or if you prefer direct usage:
image_generationskill withOPENAI_API_KEYorSTABLE_DIFFUSION_KEYsolana_agentskill with a private key environment variable
The onboarding flow will prompt for these keys. Provide or skip if optional.
The system can handle multiple LLMs simultaneously, e.g.:
- Activity Selector => cheap GPT-3.5
- Code Generation => GPT-4
- Daily Analysis => local GPT4All
All you need is to enable the correct skill(s) in skills_config.json and optionally specify which model each feature uses. The default is to just pick one skill for everything.
-
AnalyzeDailyActivity
- Reads recent memory, calls your LLM-of-choice, logs a short reflection.
-
SuggestNewActivities
- Brainstorms new tasks or expansions relevant to your objectives and constraints.
-
BuildOrUpdateActivity
- Takes suggestions, calls an LLM to generate
.pycode, writes toactivities/, reloads dynamically.
- Takes suggestions, calls an LLM to generate
- Under Onboarding or Configuration, fill in name, personality, objectives, constraints.
- Click Save.
- In the Integrations or Skills tab, pick an app (e.g., Twitter).
- Complete OAuth via Composio.
- Confirm the status is “Connected.”
- Once everything is set, click Start.
- Real-time logs show which Activity is chosen, memory usage, or new code generation.
- Pause or Stop anytime.
python my_digital_being/tools/onboard.py(It will re-check your config, letting you update or skip certain steps.)
python -m framework.mainLogs appear in your console. Press Ctrl+C to stop.
If you want your AI being to deploy tokens or interact with the Solana blockchain, you could rely on Composio (if supported) or manually add a skill that wraps Solana-AgentKit. Below is a minimal example that shows how to create a new skill in skills/, configure your key, and then reference it in an activity.
In skills/skill_solana_agent.py, you might write:
"""
Solana AgentKit Skill
This skill wraps solana-agent-kit for token deployment or other on-chain actions.
"""
import logging
import os
from typing import Optional
from framework.api_management import api_manager
logger = logging.getLogger(__name__)
class SolanaAgentSkill:
def __init__(self):
self.skill_name = "solana_agent"
self.required_api_keys = ["SOLANA_PRIVATE_KEY"]
# Register required keys with the system
api_manager.register_required_keys(self.skill_name, self.required_api_keys)
self.private_key: Optional[str] = None
async def initialize(self) -> bool:
"""
Fetch the SOLANA_PRIVATE_KEY from the secret storage (env or .env, etc.)
Optionally test connectivity or run a minimal transaction if desired.
"""
try:
self.private_key = await api_manager.get_api_key(self.skill_name, "SOLANA_PRIVATE_KEY")
if not self.private_key:
logger.error("Solana private key not configured")
return False
# Here you could do a minimal validation or connection check if needed
logger.info("SolanaAgentSkill initialized successfully")
return True
except Exception as e:
logger.error(f"Error initializing SolanaAgentSkill: {e}")
return False
async def deploy_token(self, name: str, symbol: str, supply: int, decimals: int = 9) -> dict:
"""
Example method to deploy a new token using solana-agent-kit logic.
"""
if not self.private_key:
logger.error("Skill not initialized, missing private key")
return {"success": False, "error": "Skill not initialized"}
try:
logger.info(f"Deploying token '{name}' on Solana with supply={supply}")
# Pseudocode:
# agent = SolanaAgentKit(self.private_key, "https://api.mainnet-beta.solana.com")
# result = await agent.deployToken(name, "uri", symbol, decimals, supply)
# return {"success": True, "mint": result["mint_address"]}
# For demonstration, return a dummy result
return {"success": True, "mint": "FakeMint123"}
except Exception as e:
logger.error(f"deploy_token error: {e}")
return {"success": False, "error": str(e)}
# A global instance if you like
solana_agent_skill = SolanaAgentSkill()Here’s what’s happening:
skill_name = "solana_agent".- We call
api_manager.register_required_keys(...)with["SOLANA_PRIVATE_KEY"]. initialize()loads the private key from secure storage.deploy_token(...)is an example method for real Solana logic—here it’s just a stub.
Open config/skills_config.json and add:
{
"solana_agent": {
"enabled": true,
"required_api_keys": ["SOLANA_PRIVATE_KEY"],
"api_key_mapping": {
"SOLANA_PRIVATE_KEY": "SOLANA_PRIVATE_KEY"
}
}
// ... other skills ...
}(Now the onboarding wizard or the web UI can prompt for SOLANA_PRIVATE_KEY if missing.)
Next, we define an Activity that calls solana_agent_skill.deploy_token(...). You can do this manually or let the AI produce code. Here’s a manual sample:
# activities/activity_deploy_solana_token.py
import logging
from framework.activity_decorator import activity, ActivityBase, ActivityResult
from skills.skill_solana_agent import solana_agent_skill
logger = logging.getLogger(__name__)
@activity(
name="deploy_solana_token",
energy_cost=1.0,
cooldown=2592000, # e.g. 30 days
required_skills=["solana_agent"]
)
class DeploySolanaTokenActivity(ActivityBase):
async def execute(self, shared_data) -> ActivityResult:
try:
logger.info("Starting DeploySolanaTokenActivity...")
# Initialize skill if not done already
if not await solana_agent_skill.initialize():
return ActivityResult(
success=False,
error="Failed to init Solana agent skill"
)
# Example config from shared data or state
token_info = {
"name": "My AI Token",
"symbol": "AIT",
"supply": 1000000,
"decimals": 9
}
result = await solana_agent_skill.deploy_token(
name=token_info["name"],
symbol=token_info["symbol"],
supply=token_info["supply"],
decimals=token_info["decimals"]
)
if not result["success"]:
return ActivityResult(
success=False,
error=result.get("error", "Unknown error from Solana skill")
)
logger.info(f"Token deployed with mint: {result['mint']}")
return ActivityResult(
success=True,
data={"mint_address": result["mint"]}
)
except Exception as e:
logger.error(f"Error in DeploySolanaTokenActivity: {e}")
return ActivityResult(success=False, error=str(e))If you want to limit how often this token can be deployed, you can define constraints in activity_constraints.json. For instance:
{
"activity_cooldowns": {
"DeploySolanaTokenActivity": 2592000
},
"activity_requirements": {
"DeploySolanaTokenActivity": {
"required_skills": ["solana_agent"]
}
}
}(Now the system sees that DeploySolanaTokenActivity needs the solana_agent skill and has a 30-day cooldown.)
The system auto-reloads new Activities. If you just created activity_deploy_solana_token.py, you can either restart the agent or wait for the hot-reload if configured. Once running, the being might eventually choose this Activity if it meets constraints, or you can force it by removing cooldowns or making it your only viable option.
- Ease of Use: Our built-in “BuildOrUpdateActivity” can spontaneously propose new code, saving you from manual creation.
- Web UI: You can manually edit or refine the Python code from the interface.
- Advanced Devs: If you have specialized needs (like specific constraints or external libraries not well-suited to Composio), manual skill creation is perfect.
- Rely on the AI: The being can spontaneously propose new
.pycode viaBuildOrUpdateActivity. Approve or refine in the Web UI. - Manual: Similar steps as above—create
activity_*.py, define a class with the@activity()decorator, set constraints inactivity_constraints.json.
Either way, once recognized, the new Activity is eligible for selection in the main loop.
- Short-term: Recent logs or activity results (up to ~100).
- Long-term: Older logs archived by category.
- Holds the being’s “energy,” “mood,” timestamps, or custom fields.
- Filters out activities that fail cooldown/skill constraints.
- If multiple remain, calls an LLM to decide.
- If none remain, might propose new activities to fill a gap.
- Web UI: Click Stop or Pause.
- CLI: Press
Ctrl+C.
Memory/state persist, so you can resume next time.
We welcome PRs and feedback!
- Fork this repo.
- Create a feature branch for your changes.
- Add/Improve code or docs.
- Open a pull request—maintainers will review and merge.
This project is licensed under the MIT License. See the LICENSE file.
That’s it! We hope you enjoy building with the Pippin Framework. Whether you want your AI to brainstorm content, spin up tokens on Solana, or implement an entirely new skill from scratch, we’ve got you covered. If you have any questions or suggestions, please reach out or open an issue—happy hacking!