porkfry-ai 0.2.0
Enterprise AI Agent Platform - CLI, API, and SDK for building AI agents
License: MIT
Requires Python: <3.14,>=3.12
Keywords: agents, ai, anthropic, claude, fastapi, gpt, llm, mcp, openai

# Porkfry

[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://img.shields.io/badge/tests-5892%20passing-brightgreen.svg)](#testing)

> 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

```bash
# 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 |

```bash
# 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

```bash
# 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:

```bash
# 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

```bash
# 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** |

```bash
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](docs/INSTALLATION.md) | Installation methods and requirements |
| [CLI Reference](docs/CLI.md) | Complete CLI command reference |
| [API Reference](docs/API.md) | REST API documentation |
| [Local Mode](docs/LOCAL_MODE.md) | Running without infrastructure |
| [Architecture](docs/ARCHITECTURE.md) | System design and module overview |
| [MCP Integration](docs/MCP.md) | Model Context Protocol setup |
| [Channels](docs/CHANNELS.md) | Channel integration guide |
| [Providers](docs/PROVIDERS.md) | LLM provider configuration |
| [Open Core](docs/OPEN_CORE.md) | Licensing boundary details |

## Contributing

Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style, and PR process.

## License

[MIT](LICENSE) for the core platform. Enterprise features under separate [commercial license](LICENSE-ENTERPRISE).