# AGENTS.md - Momentry Core

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

## Build & Run Commands

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

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

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

```rust
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)

```rust
#[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

```rust
#[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)