From 727bc0bca6d93d70e4ea230c68a4c08d14395d8b Mon Sep 17 00:00:00 2001 From: 0xZensh Date: Wed, 22 Jan 2025 15:42:34 +0800 Subject: [PATCH] chore: add more documents to `anda_core` --- Cargo.lock | 2 +- anda_core/Cargo.toml | 2 +- anda_core/README.md | 90 ++++++++++++++++++++++++++++++++++++++-- anda_core/src/agent.rs | 34 +++++++++++++++ anda_core/src/context.rs | 40 ++++++++++++++++++ anda_core/src/http.rs | 19 +++++++++ anda_core/src/model.rs | 13 ++++++ anda_core/src/tool.rs | 27 ++++++++++++ 8 files changed, 221 insertions(+), 6 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index cb7ecc6..8b7c0ee 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -147,7 +147,7 @@ dependencies = [ [[package]] name = "anda_core" -version = "0.3.2" +version = "0.3.3" dependencies = [ "bytes", "candid", diff --git a/anda_core/Cargo.toml b/anda_core/Cargo.toml index 6d0d58d..02c82f3 100644 --- a/anda_core/Cargo.toml +++ b/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 diff --git a/anda_core/README.md b/anda_core/README.md index d4cb205..ad9775c 100644 --- a/anda_core/README.md +++ b/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). diff --git a/anda_core/src/agent.rs b/anda_core/src/agent.rs index d04654f..119375a 100644 --- a/anda_core/src/agent.rs +++ b/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}; diff --git a/anda_core/src/context.rs b/anda_core/src/context.rs index 2811186..d44b9c8 100644 --- a/anda_core/src/context.rs +++ b/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}; diff --git a/anda_core/src/http.rs b/anda_core/src/http.rs index 10c28b6..6dc3558 100644 --- a/anda_core/src/http.rs +++ b/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; diff --git a/anda_core/src/model.rs b/anda_core/src/model.rs index d8f01ed..e5d5a2a 100644 --- a/anda_core/src/model.rs +++ b/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}; diff --git a/anda_core/src/tool.rs b/anda_core/src/tool.rs index ecfae8a..52b4161 100644 --- a/anda_core/src/tool.rs +++ b/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};