porkfry-ai 0.1.0

Enterprise AI Agent Platform - CLI, API, and SDK for building AI agents

Porkfry

Open-source, multi-tenant AI agent platform. Self-host or deploy to cloud.

Porkfry is a full-stack platform for building, deploying, and managing AI agents. It connects to 13+ LLM providers, 16 messaging channels, 38+ tools, and learns from every interaction through episodic-to-semantic memory consolidation. Run it on your laptop with porkfry serve or deploy it as a multi-tenant API.

Quick Start

# Install
pip install porkfry-ai

# Start the server (local mode — no Docker, no Postgres, no Redis)
porkfry serve

# Or jump straight into chat
porkfry chat

Access the API at http://localhost:8000. That's it — local mode uses SQLite and in-memory caching, so there's nothing else to set up.

Why Porkfry

• Genuinely learns — Episodic-to-semantic memory consolidation means the agent remembers your preferences, coding style, and domain expertise across sessions. It gets better the more you use it.
• Any model, any provider — Anthropic, OpenAI, Google, AWS Bedrock, Groq, Together, Ollama, llama.cpp, and more. Switch models with one config change.
• Cost-aware routing — Thompson Sampling bandit automatically routes requests to the cheapest model that meets quality thresholds. Track savings in real-time.
• Self-correcting — Reflexion engine detects failures, generates self-critiques, and retries with learned insights. Cross-session reflection storage means mistakes are never repeated.
• Works everywhere — Discord, Slack, Telegram, WhatsApp, Teams, Matrix, Signal, iMessage, and 9 more channels out of the box.
• Production-ready — Multi-tenant API, RBAC, SSO (SAML/OIDC), audit logging, rate limiting, budget enforcement, and OpenTelemetry tracing.

Architecture

                                ┌─────────────────────────────────────┐
                                │            Porkfry Core             │
                                │                                     │
  Channels ──────────┐          │  ┌─────────┐  ┌──────────────────┐  │
  (Discord, Slack,   │          │  │  Agent   │  │   Memory System  │  │
   Telegram, etc.)   ├──────────┤  │  Loop    │  │  ┌────────────┐ │  │
                     │          │  │  ┌─────┐ │  │  │ Episodic   │ │  │
  CLI / TUI ─────────┤          │  │  │Plan │ │  │  │ Store      │ │  │
                     │          │  │  │Exec │ │  │  ├────────────┤ │  │
  REST API ──────────┤          │  │  │Eval │ │  │  │ Semantic   │ │  │
                     │          │  │  └─────┘ │  │  │ Store      │ │  │
  WebSocket ─────────┘          │  └────┬─────┘  │  ├────────────┤ │  │
                                │       │        │  │ Consolid-  │ │  │
  ┌───────────────────┐         │  ┌────▼─────┐  │  │ ation      │ │  │
  │   LLM Providers   │         │  │Middleware│  │  └────────────┘ │  │
  │                   │         │  │ Chain    │  └──────────────────┘  │
  │  Anthropic        │◄────────┤  └────┬─────┘                      │
  │  OpenAI           │         │       │        ┌──────────────────┐  │
  │  Google Gemini    │         │  ┌────▼─────┐  │   Intelligence   │  │
  │  AWS Bedrock      │         │  │  Tools   │  │  ┌────────────┐ │  │
  │  Groq             │         │  │  (38+)   │  │  │ Cost Route │ │  │
  │  Together         │         │  └──────────┘  │  │ Reflexion  │ │  │
  │  Ollama           │         │                │  │ User Model │ │  │
  │  llama.cpp        │         │  ┌──────────┐  │  │ Debate     │ │  │
  │  + 5 more         │         │  │  Skills  │  │  │ CoT Steer  │ │  │
  └───────────────────┘         │  │  (25)    │  │  └────────────┘ │  │
                                │  └──────────┘  └──────────────────┘  │
                                └─────────────────────────────────────┘

Features

LLM Providers (13+)

Provider	Type	Models
Anthropic	Cloud	Claude Opus, Sonnet, Haiku
OpenAI	Cloud	GPT-4o, GPT-4 Turbo, o1
Google	Cloud	Gemini 2.0 Flash, 1.5 Pro
AWS Bedrock	Cloud	Claude, Llama, Mistral via AWS
Groq	Cloud	Llama 3.3 70B, Mixtral
Together	Cloud	Meta Llama, Mistral
Fireworks	Cloud	Fast inference
Mistral	Cloud	Mistral Large, Medium
OpenRouter	Cloud	Model aggregator
Perplexity	Cloud	Search-augmented
DeepInfra	Cloud	Open-source models
Ollama	Local	Any GGUF model
llama.cpp	Local	Direct GGUF inference
vLLM	Local	High-throughput serving
LM Studio	Local	GUI + API

Provider features: Failover chains, circuit breakers, response caching, auth key rotation, model aliases, token counting, cost tracking.

Channels (16)

Channel	Status	Features
Discord	Supported	Slash commands, embeds, threads
Slack	Supported	App home, blocks, modals
Telegram	Supported	Inline queries, groups, channels
WhatsApp	Supported	Templates, media, groups
Microsoft Teams	Supported	Adaptive cards, tabs
Google Chat	Supported	Spaces, cards
Matrix	Supported	E2EE, federation
Signal	Supported	Groups, sealed sender
iMessage	Supported	Via BlueBubbles
Twitch	Supported	Chat commands
LINE	Supported	Rich menus, Flex messages
Zalo	Supported	OA messages
Nextcloud	Supported	Talk integration
Mattermost	Supported	Slash commands, plugins
Nostr	Supported	Relay-based messaging
Tlon	Supported	Urbit integration
Webchat	Supported	Embeddable widget

Channel features: Outbound message queue with retry, message deduplication, typing indicators, per-channel chunking, inbound debouncing, PII sanitization.

Tools (38+)

Built-in (13): Calculator, Canvas, Code Interpreter, File System, HTTP Request, JSON Query, Memory, PDF Extract, Shell, Stateful Shell, Web Fetch, Web Search

Coding (5): Code Edit, Code Navigation (LSP), Git, Project Context, Test Runner

Extended (19 categories): AI/ML, Analytics, Communication, Delegation, Development, Device, Enterprise, Integrations, Media, Memory, Orchestration, Persistence, Production, Productivity, Reasoning, Smart Home, System, Utility

Tool features: 3-tier sandboxing (bundled/installed/untrusted), policy-based access control, tool profiles for customization, execution approval workflows.

Skills (25 Bundled)

Pre-built skill packs: 1Password, API Tester, AWS, Calendar, Code, Data Analysis, Database, Docker, Email, File Manager, GitHub, Image Generation, Jira, Kubernetes, Notes, PDF, Reminders, Shell, Slack Admin, Smart Home, Spotify, Summarize, Translate, Weather, Web Search

Skill system: SKILL.md manifest format, community registry with reviews and versioning, auto-discovery, 3-tier sandboxing, skill evolution (Voyager-style learning from interactions).

Voice

Provider	Direction	Type
Edge TTS	Text-to-Speech	Cloud (free)
ElevenLabs	Text-to-Speech	Cloud
OpenAI TTS	Text-to-Speech	Cloud
Local TTS	Text-to-Speech	Offline
Whisper	Speech-to-Text	Cloud
Whisper Local	Speech-to-Text	Offline

Voice features: VAD (voice activity detection), wake word detection, continuous talk mode, Twilio phone integration.

Intelligence Features

These research-backed capabilities make Porkfry agents genuinely intelligent:

Adaptive Cost Router

Based on: Contextual Bandits, Thompson Sampling

Automatically routes each request to the cheapest LLM that meets quality thresholds. The bandit learns from outcomes — over time, simple queries go to fast/cheap models while complex tasks go to capable ones. Tracks cost savings in real-time via the /v1/cost/ dashboard API.

Reflexion (Self-Correcting Agents)

Based on: Shinn et al. 2023 — 91% on HumanEval

When an agent fails, it generates a verbal self-critique, stores the lesson, and retries with that insight injected into context. Reflections persist across sessions, so the agent never makes the same mistake twice. Pluggable evaluators: heuristic, code analysis, LLM judge, or composite.

Memory Consolidation

Based on: Mem0 2025, MemGPT, Ebbinghaus Forgetting Curve

Raw interactions are stored as episodic memories with auto-scored importance and emotional valence. A background consolidation process clusters related episodes, extracts semantic patterns (preferences, facts, skills), and promotes them to long-term semantic memory. Unused episodic memories decay naturally via the Ebbinghaus forgetting curve.

Cognitive User Modeling

Based on: MACRec 2024, Agentic Recommender Systems

Tracks behavioral signals (message length, topics, vocabulary, timing) to build an evolving user profile. Infers expertise level per domain, communication preferences, and interests. Generates per-user adaptation prompts so the agent adjusts its style automatically. Full transparency: users can view, override, or delete any inferred preference via the /v1/profile/ API.

Proactive Agent Mode

Based on: CHI 2025 Inner Thoughts, SIGIR 2024 Proactive Agents

Context monitors (git, dependencies, schedules, channel patterns) feed events into an inner thought engine that decides whether to proactively speak up. Confidence-weighted intervention: high-confidence actions execute automatically, medium-confidence suggestions queue for user review, low-confidence thoughts are discarded. Configurable policy with cooldowns, rate limits, and blocked hours.

Skill Evolution

Based on: Wang et al. 2023 (Voyager) — 3.3x capability growth

Extracts reusable patterns from successful interactions, verifies them against test cases, and promotes verified skills to a library that agents can reuse. Skills compose into higher-order skills. An auto-curriculum system proposes learning goals based on current skill gaps and tracks per-domain mastery.

Multi-Agent Debate

Based on: Du et al. 2023, ICLR 2025 Scaling Analysis

For complex or high-stakes queries, multiple agents with different roles (analyst, critic, synthesizer, devil's advocate) debate the answer across rounds. Convergence detection (key-point Jaccard similarity) stops the debate when consensus is reached. The synthesizer produces a structured final answer that acknowledges disagreements.

Chain-of-Thought Steering

Based on: CREST 2025 Cognitive Attention Heads

Monitors reasoning traces in real-time to detect: circular reasoning (loop detection), hallucination risk (hedging language, confidence drops), contradictions, topic drift, and complexity explosion. When issues are detected, the system injects targeted corrections to steer reasoning back on track.

Security

• Authentication: API keys, JWT tokens, MFA (TOTP/SMS)
• SSO: SAML 2.0, OpenID Connect
• Directory Sync: SCIM provisioning
• Authorization: RBAC with custom roles, group policies, mention gating
• Prompt Injection: Detection and prevention
• Execution Approvals: Policy-based approval workflows for tool execution
• Audit Logging: Full action audit trail with search API
• Key Rotation: Automatic API key rotation across providers
• Sandboxing: Docker-based sandbox for code execution (host mode for development)
• Credential Vault: Encrypted storage for secrets
• Data Compliance: GDPR support (deletion requests, exports, consent records, retention policies)

Observability

• OpenTelemetry: Distributed tracing via OTLP (auto-instrumented: FastAPI, HTTPX, SQLAlchemy, Redis)
• Prometheus: Metrics endpoint at /metrics
• Sentry: Error tracking and performance monitoring
• Structured Logging: structlog with JSON or console output
• Diagnostic Logging: Ring-buffer diagnostic logs with PII redaction
• Heartbeat: Component health probes (DB, Redis, LLM providers, channels)
• Budget Alerts: Real-time cost monitoring with configurable alert thresholds

Infrastructure

• Daemon Mode: Background service via launchd (macOS) or systemd (Linux)
• SSH Tunnels: Managed tunneling for remote access
• Tailscale: VPN mesh networking integration
• mDNS Discovery: Local network agent discovery via Bonjour/Avahi
• Wide-Area DNS: Service discovery across networks
• Container Pool: Pre-warmed Docker container pool for fast sandbox startup

API

The REST API covers every aspect of the platform:

Endpoint Group	Description
/v1/agents	CRUD, invoke, streaming
/v1/conversations	History, export, archive
/v1/memory	Episodic/semantic storage and search
/v1/skills	Install, discover, manage
/v1/tools	Enable, disable, profiles
/v1/channels	Configure, test, webhooks
/v1/analytics	Usage, cost summaries
/v1/cost	Routing stats, savings dashboard
/v1/profile	User preferences, expertise, transparency
/v1/proactive	Suggestions, triggers, policy
/v1/community	Skill registry, reviews, submissions
/v1/health	Liveness, readiness, heartbeat
/v1/auth	Login, tokens, MFA
/v1/webhooks	Outbound webhook config and replay

# Create an agent
curl -X POST http://localhost:8000/v1/agents \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "assistant", "model": "claude-sonnet-4-20250514"}'

# Invoke with streaming
curl -X POST http://localhost:8000/v1/agents/{agent_id}/invoke \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Explain the architecture of this codebase"}' \
  --no-buffer

CLI

# Interactive chat
porkfry chat

# One-shot prompt
porkfry run "What is the capital of France?"

# Pipe input
cat error.log | porkfry run "What's wrong here?"

# Voice mode
porkfry talk

# Manage agents
porkfry agents list
porkfry agents create --name "coder" --model "claude-sonnet-4-20250514"

# Manage channels
porkfry channels list
porkfry channels test discord

# Skills
porkfry skills list
porkfry skills install github

# Server
porkfry serve              # Local mode (SQLite, no dependencies)
porkfry serve --reload     # Development with hot reload

# System diagnostics
porkfry system doctor
porkfry system logs --tail

Configuration

All settings are configured via environment variables or .env file:

# LLM Providers
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=AI...

# Or use local models
OLLAMA_BASE_URL=http://localhost:11434/v1

# Database (optional — defaults to SQLite in local mode)
DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/porkfry

# Redis (optional — in-memory fallback in local mode)
REDIS_URL=redis://localhost:6379

# Intelligence features (all opt-in)
COST_ROUTING_ENABLED=true
REFLEXION_ENABLED=true
CONSOLIDATION_ENABLED=true
USER_MODELING_ENABLED=true
PROACTIVE_ENABLED=true
SKILL_EVOLUTION_ENABLED=true
DEBATE_ENABLED=true
COT_STEERING_ENABLED=true

See app/core/config.py for the full list of 100+ configuration options.

Development

# Clone
git clone https://github.com/victordeascencao/Porkfry.git
cd Porkfry

# Setup
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest                              # Full suite (5892 tests)
pytest tests/test_debate.py -v      # Single module
pytest -x --tb=short -q             # Fast regression

# Start dev server
porkfry serve --reload

Testing

The test suite covers every module with 5,892 passing tests:

Category	Tests
Core platform (8 rounds, 65 features)	~5,238
Cost Router + Reflexion	218
Memory Consolidation + User Modeling	121
Proactive Agents + Skill Evolution	170
Multi-Agent Debate + CoT Steering	145
Total	5,892 passing, 62 skipped

pytest tests/ -x --tb=short -q
# 5892 passed, 62 skipped in ~60s

Tech Stack

Component	Technology
Language	Python 3.12+
Framework	FastAPI (async)
ORM	SQLAlchemy 2.0 (async)
Database	PostgreSQL + pgvector / SQLite + aiosqlite
Cache	Redis / In-memory fallback
Task Queue	ARQ (Redis-based)
CLI	Typer + Rich
TUI	Textual
Tracing	OpenTelemetry
Metrics	Prometheus
Errors	Sentry
Logging	structlog

Codebase

Metric	Count
Application code	~162,000 lines
Test code	~90,000 lines
Source files	397
Test files	199
Database models	57
API routers	25
Alembic migrations	10

Open-Core Licensing

Porkfry uses an open-core model:

Edition	Price	Includes
Community	Free (MIT)	Core runtime, all LLM providers, 38+ tools, 16 channels, 25 skills, memory, voice, CLI/SDK, all intelligence features
Team	$99/user/mo	SSO (SAML/OIDC), SCIM, custom RBAC, private skill registries, advanced audit
Enterprise	Custom	HA clustering, audit export, compliance, cost attribution, SLA

Documentation

Document	Description
Installation	Installation methods and requirements
CLI Reference	Complete CLI command reference
API Reference	REST API documentation
Local Mode	Running without infrastructure
Architecture	System design and module overview
MCP Integration	Model Context Protocol setup
Channels	Channel integration guide
Providers	LLM provider configuration
Open Core	Licensing boundary details

Contributing

Contributions welcome. See CONTRIBUTING.md for development setup, code style, and PR process.

License

MIT for the core platform. Enterprise features under separate commercial license.