# `lib.rs` – Public Library Facade

## Purpose
`lib.rs` provides a **high‑level ergonomic API** that wraps the core Todozi functionality for external consumption. It re‑exports common structs and helper functions so that other Rust crates (or scripts) can interact with Todozi without dealing directly with storage, embedding, or agent internals.

## Main Public Items

| Item | Category | Description |
|------|----------|-------------|
| `Done` | Struct | Primary façade for task‑centric operations: `create_task`, `update_task`, `delete_task`, `search_tasks`, etc. |
| `Tdz` | Struct | Simplified helper for quick task creation and project selection (e.g., `Tdz::set_project`). |
| `Actions` | Module | Helper functions for creating tasks with specific assignee types (human, AI, collaborative). |
| `Tags` | Module | Tag parsing utilities (`parse_tags`, `format_tags`). |
| `Projects` | Module | Project‑management APIs (`create_project`, `list_projects`, `archive_project`). |
| `Memories` | Module | Memory CRUD (`add_memory`, `list_memories`, `search_memories`). |
| `Ideas` | Module | Idea CRUD (`add_idea`, `list_ideas`). |
| `Queue` | Module | Queue workflow (`plan_queue_item`, `list_queue`, `start_session`, `end_session`). |
| `Find` | Module | Unified search façade that delegates to keyword, semantic, or clustered search back‑ends. |
| `Emb` | Module | Wrapper around `TodoziEmbeddingService` for embedding generation, backup, and validation. |
| `Stats` | Module | Analytics and reporting utilities (`generate_daily_summary`, `export_summary_csv`). |
| `Easy` | Module | Minimal‑boilerplate API for quick scripts (`Easy::quick_add`, `Easy::quick_search`). |

## Example Usage

```rust
use todozi::Done;
use todozi::Priority;
use todozi::Status;

#[tokio::main]
async fn main() -> todozi::error::Result<()> {
    // Initialise the library (creates ~/.todozi if needed)
    Done::init().await?;

    // Create a new high‑priority task
    let task = Done::create_task(
        "Implement OAuth login flow",
        Some(Priority::High),
        None,               // Use currently set project
        Some("2h"),         // Estimated time
        Some("Security module") // Context notes
    ).await?;

    println!("🆕 Created task {}", task.id);

    // Perform a semantic search for related tasks
    let matches = Done::search_tasks("authentication", true, Some(5)).await?;
    for m in matches {
        println!("🔎 Found {} – {}", m.id, m.action);
    }

    Ok(())
}
```

## Design Rationale

* **Encapsulation** – All low‑level concerns (file paths, HLX handling, embedding caching) are hidden behind tidy methods.
* **Async‑first** – Public functions are async, allowing callers to integrate easily with `tokio` or other async runtimes.
* **Extensibility** – New domains (e.g., `Chat`, `Training`) can be added as separate modules and re‑exported here without breaking existing code.
* **Consistency** – Error handling uses the unified `Result<T>` type from `error.rs`, making propagation uniform across the crate.

## Integration Points

| Module | Interaction |
|--------|-------------|
| `src/storage.rs` | All CRUD operations ultimately call into `Storage`. |
| `src/emb.rs` | Semantic search and embedding‑related functions are delegated to `Emb`. |
| `src/agent.rs` | Agent‑specific helpers (`assign_task_to_agent`, `run_agent`) are accessed via `Done::assign_agent`. |
| `src/server.rs` | The HTTP API maps directly to the same public methods exposed here, ensuring the server and library stay in sync. |
| `src/cli.rs` | CLI sub‑commands are thin wrappers around the functions re‑exported in `lib.rs`. |

## Testing

The library is exercised by integration tests in `src/tests.rs`. Typical test patterns:

```rust
#[tokio::test]
async fn test_create_and_search() {
    Done::init().await.unwrap();
    let task = Done::create_task("Write docs", Some(Priority::Medium), None, None, None).await.unwrap();
    let results = Done::search_tasks("docs", false, Some(10)).await.unwrap();
    assert!(results.iter().any(|t| t.id == task.id));
}
```

## See Also

* `src/models.rs` – Core data structures (`Task`, `Agent`, `Memory`, etc.).
* `src/error.rs` – Unified error handling (`TodoziError`).
* `src/emb.rs` – Embedding service used by `Emb` and `Find`.
* `src/cli.rs` – Command‑line wrappers that invoke the same public APIs.
* `docs/cmd.md` – Overview of all top‑level CLI commands.

---

*Generated by GPT‑OSS – documentation for the `lib.rs` façade.*
