chore: add more documents to anda_core

anda_core/Cargo.toml

@@ -3,7 +3,7 @@ name = "anda_core"
 description = "Core types and traits for Anda -- a framework for AI agent development."
 repository = "https://github.com/ldclabs/anda/tree/main/anda_core"
 publish = true
-version = "0.3.2"
+version = "0.3.3"
 edition.workspace = true
 keywords.workspace = true
 categories.workspace = true

anda_core/README.md

@@ -1,12 +1,94 @@
-# `anda_core`
+# `anda_core` Anda Core Library
 
-[![Crates.io](https://img.shields.io/crates/v/anda_core)](https://crates.io/crates/anda_core)
-[![Documentation](https://docs.rs/anda_core/badge.svg)](https://docs.rs/anda_core)
+![License](https://img.shields.io/crates/l/anda_core.svg)
+[![Crates.io](https://img.shields.io/crates/d/anda_core.svg)](https://crates.io/crates/anda_core)
+[![Test](https://github.com/ldclabs/anda/actions/workflows/test.yml/badge.svg)](https://github.com/ldclabs/anda/actions/workflows/test.yml)
+[![Docs.rs](https://docs.rs/anda_core/badge.svg)](https://docs.rs/anda_core)
+[![Latest Version](https://img.shields.io/crates/v/anda_core.svg)](https://crates.io/crates/anda_core)
 
-Core types and traits for Anda.
+The Anda Core Library provides the fundamental building blocks for creating and managing AI agents and tools in a modular, secure, and extensible system.
 
 More information about this crate can be found in the [crate documentation][docs].
 
+## Key Features
+
+- **Modular Architecture**: Separates concerns into distinct modules for agents, tools, context, and models
+- **Type Safety**: Strongly typed interfaces for agent and tool definitions
+- **Asynchronous Execution**: All operations are async for efficient I/O handling
+- **Dynamic Dispatch**: Supports runtime polymorphism for agents and tools
+- **Security Features**: Includes cryptographic operations and verified caller information
+- **Extensibility**: New features can be added through modular trait implementations
+
+## Core Modules
+
+### 1. Agent Module [`agent.rs`](https://github.com/ldclabs/anda/blob/main/anda_core/src/agent.rs)
+Provides core functionality for creating and managing AI agents:
+- `Agent` trait for defining custom agents
+- `AgentDyn` trait for runtime polymorphism
+- `AgentSet` for managing multiple agents
+
+### 2. Tool Module [`tool.rs`](https://github.com/ldclabs/anda/blob/main/anda_core/src/tool.rs)
+Defines the core functionality for creating and managing tools:
+- `Tool` trait for defining custom tools with typed arguments
+- `ToolDyn` trait for runtime polymorphism
+- `ToolSet` for managing multiple tools
+
+### 3. Context Module [`context.rs`](https://github.com/ldclabs/anda/blob/main/anda_core/src/context.rs)
+Provides the execution environment for agents and tools:
+- `AgentContext` as the primary interface combining all capabilities
+- `BaseContext` for fundamental operations
+- Feature sets including:
+  - State management
+  - Cryptographic operations
+  - Persistent storage
+  - In-memory caching
+  - HTTP communication
+  - Blockchain interactions
+
+### 4. Model Module [`model.rs`](https://github.com/ldclabs/anda/blob/main/anda_core/src/model.rs)
+Defines core data structures and interfaces for LLMs:
+- Agent output and message structures
+- Function definitions with JSON schema support
+- Knowledge and document handling
+- Completion and embedding request/response structures
+- Core AI capabilities traits
+
+### 5. HTTP Module [`http.rs`](https://github.com/ldclabs/anda/blob/main/anda_core/src/http.rs)
+Provides utilities for making RPC calls:
+- CBOR-encoded RPC calls
+- Candid-encoded canister calls
+- HTTP request/response handling
+- Error handling for RPC operations
+
+## Key Concepts
+
+### Agent System
+- Agents implement specific capabilities through the `Agent` trait
+- Agents can be dynamically selected and executed at runtime
+- Agents can depend on multiple tools for functionality
+
+### Tool System
+- Tools provide specific functionality through the `Tool` trait
+- Tools can be called with strongly-typed arguments
+- Tools support both direct and JSON-based execution
+
+### Context System
+- Provides the execution environment for agents and tools
+- Modular design allows for flexible feature composition
+- Includes security features like cryptographic operations
+
+### Knowledge Management
+- Supports semantic search and document storage
+- Allows adding and retrieving knowledge documents
+- Provides both similarity-based and time-based retrieval
+
+## Security Features
+- Cryptographic key derivation and management
+- Message signing and verification
+- Secure storage operations
+- Signed HTTP requests
+- Caller verification
+
 ## License
 Copyright © 2025 [LDC Labs](https://github.com/ldclabs).
 

anda_core/src/agent.rs

@@ -1,3 +1,37 @@
+//! Module providing core agent functionality for AI systems
+//!
+//! This module defines the core traits and structures for creating and managing AI agents. It provides:
+//! - The [`Agent`] trait for defining custom agents with specific capabilities
+//! - Dynamic dispatch capabilities through [`AgentDyn`] trait
+//! - An [`AgentSet`] collection for managing multiple agents
+//!
+//! # Key Features
+//! - Type-safe agent definitions with clear interfaces
+//! - Asynchronous execution model
+//! - Dynamic dispatch support for runtime agent selection
+//! - Agent registration and management system
+//! - Tool dependency management
+//!
+//! # Architecture Overview
+//! The module follows a dual-trait pattern:
+//! 1. [`Agent`] - Static trait for defining concrete agent implementations
+//! 2. [`AgentDyn`] - Dynamic trait for runtime polymorphism
+//!
+//! The [`AgentSet`] acts as a registry and execution manager for agents, providing:
+//! - Agent registration and lookup
+//! - Bulk definition retrieval
+//! - Execution routing
+//!
+//! # Usage
+//!
+//! ## Reference Implementations
+//! 1. [`Extractor`](https://github.com/ldclabs/anda/blob/main/anda_engine/src/extension/extractor.rs) -
+//!    An agent for structured data extraction using LLMs
+//! 2. [`DocumentSegmenter`](https://github.com/ldclabs/anda/blob/main/anda_engine/src/extension/segmenter.rs) -
+//!    A document segmentation tool using LLMs
+//! 3. [`CharacterAgent`](https://github.com/ldclabs/anda/blob/main/anda_engine/src/extension/character.rs) -
+//!    A role-playing AI agent, also serving as the core agent for [`anda_bot`](https://github.com/ldclabs/anda/blob/main/agents/anda_bot/README.md)
+
 use serde_json::json;
 use std::{collections::BTreeMap, future::Future, marker::PhantomData, sync::Arc};
 

anda_core/src/context.rs

@@ -1,3 +1,43 @@
+//! # Context Module
+//!
+//! This module defines the core context interfaces and traits that provide the execution environment
+//! for Agents and Tools in the ANDA system. It includes:
+//!
+//! - **AgentContext**: The primary interface combining all core functionality and AI-specific features
+//! - **BaseContext**: Fundamental operations available to all Agents and Tools
+//! - **Feature Traits**: Modular capabilities including state management, cryptographic operations,
+//!   storage, caching, and HTTP communication
+//!
+//! The context system is designed to be:
+//! - **Modular**: Features are separated into distinct traits for better organization and flexibility
+//! - **Asynchronous**: All operations are async to support efficient I/O operations
+//! - **Extensible**: New features can be added as separate traits while maintaining compatibility
+//! - **Secure**: Includes cryptographic operations and verified caller information
+//!
+//! ## Key Components
+//!
+//! ### Core Traits
+//! - [`AgentContext`]: Main interface combining all capabilities
+//! - [`BaseContext`]: Fundamental operations required by all contexts
+//!
+//! ### Feature Sets
+//! - [`StateFeatures`]: Contextual information about the execution environment
+//! - [`KeysFeatures`]: Cryptographic operations and key management
+//! - [`StoreFeatures`]: Persistent storage capabilities
+//! - [`CacheFeatures`]: In-memory caching with expiration policies
+//! - [`HttpFeatures`]: HTTP communication capabilities
+//! - [`VectorSearchFeatures`]: Semantic search functionality
+//! - [`KnowledgeFeatures`]: Knowledge base management and retrieval
+//!
+//! ### Data Structures
+//! - [`Knowledge`]: Represents a knowledge base entry
+//! - [`KnowledgeInput`]: Input structure for adding knowledge
+//! - [`CacheExpiry`]: Defines cache expiration policies
+//!
+//! ## Usage
+//! Implement these traits to create custom execution contexts for Agents and Tools. The `anda_engine` [`context`](https://github.com/ldclabs/anda/blob/main/anda_engine/src/context/mod.rs) module provides
+//! a complete implementation, but custom implementations can be created for specialized environments.
+
 use serde::{de::DeserializeOwned, Deserialize, Serialize};
 use std::{future::Future, time::Duration};
 

anda_core/src/http.rs

@@ -1,3 +1,22 @@
+//! HTTP utilities for making RPC calls to canisters and other services
+//!
+//! This module provides functionality for:
+//! - Making CBOR-encoded RPC calls
+//! - Making Candid-encoded canister calls
+//! - Handling HTTP requests and responses
+//! - Error handling for RPC operations
+//!
+//! The main types are:
+//! - [`RPCRequest`]: Represents a generic RPC request with CBOR-encoded parameters
+//! - [`CanisterRequest`]: Represents a canister-specific request with Candid-encoded parameters
+//! - [`RPCResponse`]: Represents a response from an RPC call
+//! - [`HttpRPCError`]: Represents possible errors during RPC operations
+//!
+//! The main functions are:
+//! - [`http_rpc`]: Makes a generic CBOR-encoded RPC call
+//! - [`canister_rpc`]: Makes a canister-specific RPC call with Candid encoding
+//! - [`cbor_rpc`]: Internal function for making CBOR-encoded HTTP requests
+
 use candid::{decode_args, encode_args, utils::ArgumentEncoder, CandidType, Principal};
 use ciborium::from_reader;
 use http::header;

anda_core/src/model.rs

@@ -1,3 +1,16 @@
+//! Core data models and traits for the AI agent system
+//!
+//! This module defines the fundamental data structures and interfaces used throughout the AI agent system.
+//! It includes:
+//! - Core message and conversation structures ([`AgentOutput`], [`Message`], [`ToolCall`])
+//! - Function definition and tooling support ([`FunctionDefinition`])
+//! - Knowledge and document handling ([`Document`], [`Documents`])
+//! - Completion request and response structures ([`CompletionRequest`], [`Embedding`])
+//! - Core AI capabilities traits ([`CompletionFeatures`], [`EmbeddingFeatures`])
+//!
+//! The module provides serialization support through `serde` and implements various conversion traits
+//! for seamless integration between different data representations.
+
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
 use std::{collections::BTreeMap, future::Future};

anda_core/src/tool.rs

@@ -1,3 +1,30 @@
+//! Module providing core tooling functionality for AI Agents
+//!
+//! This module defines the core traits and structures for creating and managing tools
+//! that can be used by AI Agents. It provides:
+//! - The [`Tool`] trait for defining custom tools with typed arguments and outputs
+//! - Dynamic dispatch capabilities through [`ToolDyn`] trait
+//! - A [`ToolSet`] collection for managing multiple tools
+//!
+//! # Key Features
+//! - Type-safe tool definitions with schema validation
+//! - Asynchronous execution model
+//! - Dynamic dispatch support for runtime tool selection
+//! - Tool registration and management system
+//!
+//! # Usage
+//!
+//! ## Reference Implementations
+//! 1. [`SubmitTool`](https://github.com/ldclabs/anda/blob/main/anda_engine/src/extension/extractor.rs) -
+//!    A tool for extracting structured data using LLMs
+//! 2. [`TransferTool`](https://github.com/ldclabs/anda/blob/main/tools/anda_icp/src/ledger/transfer.rs) -
+//!    A tool for handling ICP blockchain transfers
+//! 3. [`BalanceOfTool`](https://github.com/ldclabs/anda/blob/main/tools/anda_icp/src/ledger/balance.rs) -
+//!    A tool for querying ICP blockchain balances
+//!
+//! These reference implementations share a common feature: they automatically generate the JSON Schema
+//! required for LLMs Function Calling.
+
 use ic_cose_types::validate_str;
 use serde::{de::DeserializeOwned, Serialize};
 use std::{collections::BTreeMap, future::Future, marker::PhantomData, sync::Arc};