Add comprehensive documentation and examples for Owlen architecture and usage

- Include detailed architecture overview in `docs/architecture.md`.
- Add `docs/configuration.md`, detailing configuration file structure and settings.
- Provide a step-by-step provider implementation guide in `docs/provider-implementation.md`.
- Add frequently asked questions (FAQ) document in `docs/faq.md`.
- Create `docs/migration-guide.md` for future breaking changes and version upgrades.
- Introduce new examples in `examples/` showcasing basic chat, custom providers, and theming.
- Add a changelog (`CHANGELOG.md`) for tracking significant changes.
- Provide contribution guidelines (`CONTRIBUTING.md`) and a Code of Conduct (`CODE_OF_CONDUCT.md`).

examples/basic_chat.rs

@@ -0,0 +1,30 @@
+// This example demonstrates a basic chat interaction without the TUI.
+
+use owlen_core::model::Model;
+use owlen_core::session::Session;
+use owlen_ollama::OllamaProvider; // Assuming you have an Ollama provider
+use owlen_core::provider::Provider;
+
+#[tokio::main]
+async fn main() -> Result<(), anyhow::Error> {
+    // This example requires a running Ollama instance.
+    // Make sure you have a model available, e.g., `ollama pull llama2`
+
+    let provider = OllamaProvider;
+    let model = Model::new("llama2"); // Change to a model you have
+    let mut session = Session::new("basic-chat-session");
+
+    println!("Starting basic chat with model: {}", model.name);
+
+    let user_message = "What is the capital of France?";
+    session.add_message("user", user_message);
+    println!("User: {}", user_message);
+
+    // Send the chat to the provider
+    let response = provider.chat(&session, &model).await?;
+
+    session.add_message("bot", &response);
+    println!("Bot: {}", response);
+
+    Ok(())
+}

examples/custom_provider.rs

@@ -0,0 +1,39 @@
+// This example demonstrates how to implement a custom provider.
+
+use async_trait::async_trait;
+use owlen_core::model::Model;
+use owlen_core::provider::Provider;
+use owlen_core::session::Session;
+
+// Define a struct for your custom provider.
+pub struct MyCustomProvider;
+
+// Implement the `Provider` trait for your struct.
+#[async_trait]
+impl Provider for MyCustomProvider {
+    fn name(&self) -> &str {
+        "custom-provider"
+    }
+
+    async fn chat(&self, session: &Session, model: &Model) -> Result<String, anyhow::Error> {
+        println!("Custom provider received chat request for model: {}", model.name);
+        // In a real implementation, you would send the session data to an API.
+        let message_count = session.get_messages().len();
+        Ok(format!("This is a custom response. You have {} messages in your session.", message_count))
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<(), anyhow::Error> {
+    let provider = MyCustomProvider;
+    let model = Model::new("custom-model");
+    let mut session = Session::new("custom-session");
+
+    session.add_message("user", "Hello, custom provider!");
+
+    let response = provider.chat(&session, &model).await?;
+
+    println!("Provider response: {}", response);
+
+    Ok(())
+}

examples/custom_theme.rs

@@ -0,0 +1,28 @@
+// This example demonstrates how to create a custom theme programmatically.
+
+use owlen_core::theme::Theme;
+use ratatui::style::{Color, Style};
+
+fn create_custom_theme() -> Theme {
+    Theme {
+        name: "My Custom Theme".to_string(),
+        author: "Your Name".to_string(),
+        comment: "A simple custom theme".to_string(),
+        base: Style::default().fg(Color::White).bg(Color::Black),
+        user_chat: Style::default().fg(Color::Green),
+        bot_chat: Style::default().fg(Color::Cyan),
+        error: Style::default().fg(Color::Red),
+        info: Style::default().fg(Color::Yellow),
+        border: Style::default().fg(Color::Gray),
+        input: Style::default().fg(Color::White),
+        ..Default::default()
+    }
+}
+
+fn main() {
+    let custom_theme = create_custom_theme();
+
+    println!("Created custom theme: {}", custom_theme.name);
+    println!("Author: {}", custom_theme.author);
+    println!("User chat color: {:?}", custom_theme.user_chat.fg);
+}

examples/session_management.rs

@@ -0,0 +1,28 @@
+// This example demonstrates how to use the session controller.
+
+use owlen_core::session::Session;
+
+fn main() {
+    // Create a new session.
+    let mut session = Session::new("my-session");
+    println!("Created new session: {}", session.name);
+
+    // Add messages to the session.
+    session.add_message("user", "Hello, Owlen!");
+    session.add_message("bot", "Hello, user! How can I help you today?");
+
+    // Get the messages from the session.
+    let messages = session.get_messages();
+    println!("\nMessages in session:");
+    for message in messages {
+        println!("  {}: {}", message.role, message.content);
+    }
+
+    // Clear the session.
+    session.clear_messages();
+    println!("\nSession cleared.");
+
+    let messages_after_clear = session.get_messages();
+    println!("Messages in session after clear: {}", messages_after_clear.len());
+}
+