fenliu 0.1.0

monitor and filter fediverse hashtags to pass on to fedibooster for boosting

FenLiu (分流)

⚠️ DISCLAIMER / PROVISO: This project is a work in progress with major changes still happening. It is in no way anywhere close to finished and is only borderline useful for actual production use. Expect breaking changes, incomplete features, and significant architectural evolution as development continues.

Divide the Fediverse content flow

FenLiu is a web application that monitors Fediverse hashtags, filters spam, allows human review, learns from feedback, and exports quality content for boosting. Inspired by the ancient Chinese Dujiangyan irrigation system (256 BC) that separated silt from water, FenLiu applies 2,300-year engineering wisdom to modern digital content streams.

Current Status (21 February 2026)

✅ Phase 1: Foundation & MVP - COMPLETE

• Web Application: PyView-based LiveView interface with real-time capabilities
• Fediverse Integration: Fetch posts from Mastodon/Fediverse instances
• Database: SQLAlchemy models with SQLite backend
• REST API: Full CRUD operations for all entities
• Testing: Comprehensive test suite with high coverage

🔄 Phase 2: Enhanced Features - IN PROGRESS

• Spam Scoring: Basic rule-based system
• Review Interface: Manual post review workflow
• Export Functionality: FediBooster integration planning

Quick Start

Prerequisites

• Python 3.11 or higher
• uv package manager (recommended)

Installation

# Install dependencies
uv sync -U --all-groups

# Optional: Set up prek hooks
uv run prek install

Running the Application

# Development mode with auto-reload (simpler)
fenliu --reload --debug

# Alternative development mode
uv run python -m fenliu --reload --debug

# Production mode (simpler)
fenliu --host 0.0.0.0 --port 8000

# Alternative production mode
uv run python -m fenliu --host 0.0.0.0 --port 8000

# See all options
uv run fenliu --help

First Steps

1. Start the server: fenliu --reload (or uv run python -m fenliu --reload)
2. Open browser: Navigate to http://localhost:8000
3. Add a hashtag: Go to Streams page and add a hashtag (e.g., "python")
4. Fetch posts: Click "Fetch" on the hashtag stream
5. Browse posts: View fetched posts on the Posts page

API Usage

Basic Examples

# List all hashtag streams
curl http://localhost:8000/api/v1/hashtags

# Add a new hashtag stream
curl -X POST http://localhost:8000/api/v1/hashtags \
  -H "Content-Type: application/json" \
  -d '{"hashtag": "python", "instance": "mastodon.social", "active": true}'

# Fetch posts for a stream
curl -X POST http://localhost:8000/api/v1/hashtags/1/fetch?limit=20

# Get application statistics
curl http://localhost:8000/api/v1/stats

API Endpoints

• GET /api/v1/hashtags - List all hashtag streams
• POST /api/v1/hashtags - Create new stream
• GET/PATCH/DELETE /api/v1/hashtags/{id} - Stream operations
• POST /api/v1/hashtags/{id}/fetch - Fetch posts for stream
• GET /api/v1/posts - List posts with filtering
• GET /api/v1/stats - Application statistics
• GET /health - Health check
• GET /info - Application information

Project Structure

fenliu/
├── src/fenliu/
│   ├── __init__.py              # Package definition
│   ├── __main__.py              # CLI entry point
│   ├── main.py                  # PyView application
│   ├── config.py                # Application settings
│   ├── database.py              # Database configuration
│   ├── models.py                # SQLAlchemy models
│   ├── schemas.py               # Pydantic schemas
│   ├── api/                     # REST API endpoints
│   ├── services/                # Business logic
│   └── templates/               # HTML templates
├── tests/                       # Test files
├── pyproject.toml              # Project configuration
└── README.md                   # This file

Testing

# Run linting and formatting
ruff check src/fenliu/
ruff format src/fenliu/

# Run prek checks
prek run --all-files

# Run full test suite
pytest --cov=src/fenliu tests/

Configuration

Environment variables (via .env file):

# Database configuration
DATABASE_URL=sqlite:///./fenliu.db

# Fediverse settings
DEFAULT_INSTANCE=mastodon.social
API_TIMEOUT=30
MAX_POSTS_PER_FETCH=20
RATE_LIMIT_DELAY=1.0

# Application settings
DEBUG=false
SECRET_KEY=your-secret-key-change-in-production
APP_NAME=FenLiu
APP_VERSION=0.1.0

Development Workflow

After dependency changes:

uv sync -U --all-groups

Quick validation:

prek run --all-files

Full validation before commits:

nox

Technical Stack

• Framework: PyView (Starlette-based LiveView)
• Database: SQLAlchemy with SQLite
• API Client: minimal-activitypub
• Async/await: Full async support for I/O operations
• Type Hints: Comprehensive type annotations
• Validation: Pydantic for request/response validation
• Testing: pytest with async support
• Linting/Formatting: ruff with prek hooks
• Package Management: uv for fast dependency resolution

Cultural Context

The name "FenLiu" (分流) means "divide the flow" in Chinese, inspired by the ancient Dujiangyan irrigation system (256 BC). This project applies the same engineering wisdom to digital content streams, separating valuable content from spam and noise.

Documentation

• Roadmap - 5-phase development plan
• Project Summary - Overview and next steps
• LLM System Prompt - Development standards

License

AGPL-3.0 License - See LICENSE file for details.

Contributing

1. Follow the existing code style (ruff formatted)
2. Add type hints for all public functions
3. Write tests for new functionality
4. Update documentation as needed
5. Run nox before submitting changes

---

Status: Phase 1 MVP Complete ✅ Version: 0.1.0 Date: 21 February 2026 Next Phase: Enhanced filtering and review interface Framework: PyView (Starlette-based LiveView) Architecture: Async Python with comprehensive type hints