momentry_core_0_1/AGENTS.md

AGENTS.md - Momentry Core

Rust-based digital asset management system with video analysis and RAG capabilities.

Build & Run Commands

# Build project
cargo build
cargo build --release
cargo build --bin momentry

# Run CLI
cargo run -- --help
cargo run -- register /path/to/video.mp4
cargo run -- server --host 0.0.0.0 --port 3000

Testing

# Run all tests
cargo test

# Run single test by name
cargo test test_name

# Run with output
cargo test -- --nocapture

# Doc tests
cargo test --doc

Linting & Formatting

# Format code (edition=2021, max_width=100, tab_spaces=4)
cargo fmt
cargo fmt -- --check

# Lint
cargo clippy
cargo clippy --all-features

# Check for errors
cargo check
cargo check --all-features

Code Style

General

• Use Rust 2021 edition
• Use tracing for logging (not println!)
• Keep lines under 100 characters

Imports (order: std → external → local)

use std::path::Path;
use anyhow::{Context, Result};
use async_trait::async_trait;
use serde::{Deserialize, Serialize};

use crate::core::chunk::Chunk;

Error Handling

• Use anyhow::Result<T> for application code
• Use thiserror for library code
• Use .context() for error context
• Use anyhow::bail!() for early returns

fn example() -> Result<SomeType> {
    let output = Command::new("ffprobe")
        .args([...])
        .output()
        .context("Failed to run ffprobe")?;

    if !output.status.success() {
        anyhow::bail!("Command failed");
    }
    Ok(result)
}

Naming

• Types/Enums: PascalCase (VideoRecord, ChunkType)
• Functions/Variables: snake_case (get_video_by_uuid)
• Traits: PascalCase with -er suffix (Database, ChunkStore)
• Files: snake_case (postgres_db.rs)

Types

• Use serde::{Deserialize, Serialize} for serializable types
• Use #[serde(rename_all = "snake_case")] for enum variants
• Use explicit numeric types (i64, u32, f64)

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct VideoRecord {
    pub id: i64,
    pub uuid: String,
    pub duration: f64,
    pub width: u32,
}

#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum ChunkType {
    TimeBased,
    Sentence,
    Cut,
}

Async Programming

• Use tokio runtime with full features
• Use #[async_trait] for async trait methods

#[async_trait]
pub trait Database: Send + Sync {
    async fn init() -> Result<Self>
    where Self: Sized;
}

Code Structure

src/
├── main.rs           # CLI entry point
├── lib.rs            # Library exports
├── core/
│   ├── chunk/        # Chunking logic
│   ├── db/          # Database (PostgreSQL, MongoDB, Redis, Qdrant)
│   ├── embedding/   # Vector embeddings
│   ├── overlay/     # Video overlay
│   ├── probe/       # ffprobe integration
│   ├── processor/   # ASR, OCR, YOLO, Face, Pose
│   ├── storage/     # File management
│   └── thumbnail/   # Thumbnail extraction
├── api/              # HTTP API (axum)
├── player/           # Video player
└── watcher/          # File system watcher

Key Dependencies

• Error handling: anyhow, thiserror
• Async: tokio (full features), async-trait
• CLI: clap (derive)
• Serialization: serde, serde_json
• Database: sqlx, mongodb, redis, qdrant-client
• HTTP: axum, tower
• Logging: tracing, tracing-subscriber

Environment Variables

• DATABASE_URL - PostgreSQL (default: postgres://accusys@localhost:5432/momentry)

Notes

• No unit tests exist - add tests when implementing features
• Video processing uses external tools (ffprobe, Python scripts)
• Multi-database architecture (PostgreSQL, MongoDB, Redis, Qdrant)
• Monitor directory is a separate system (not Rust)