Skip to content

Commit 1a1ff5c

Browse files
roxblnfkroxblnfk
committed
Add stubs for User Guides; comment references docs
1 parent 463fc73 commit 1a1ff5c

21 files changed

Lines changed: 1427 additions & 179 deletions

‎docs/frm.tree‎

Lines changed: 0 additions & 4 deletions
This file was deleted.

‎docs/r.tree‎

Lines changed: 0 additions & 4 deletions
This file was deleted.

‎docs/topics/overview.topic‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
<title>Wippy Framework Documentation</title>
1010
<description>
1111
Build powerful AI-driven applications with actor model concurrency and intelligent agents.
12-
Wippy combines a high-performance Golang runtime implementing the actor model with a
12+
Wippy combines a high-performance Golang runtime implementing the actor model with a
1313
flexible Lua-based framework for creating intelligent AI agents and scalable applications.
1414
</description>
1515

@@ -35,12 +35,12 @@
3535
</secondary>
3636

3737
<misc>
38-
<cards>
39-
<title>Reference Documentation</title>
40-
<a href="framework-modules.md" summary="Complete reference for all 40+ framework modules including process, http, llm, and security">Framework Modules</a>
41-
<a href="configuration-reference.md" summary="YAML configuration syntax and options for all component types">Configuration Reference</a>
42-
<a href="api-reference.md" summary="Process, message, channel, registry, and agent APIs with examples">API Reference</a>
43-
</cards>
38+
<!-- <cards>-->
39+
<!-- <title>Reference Documentation</title>-->
40+
<!-- <a href="framework-modules.md" summary="Complete reference for all 40+ framework modules including process, http, llm, and security">Framework Modules</a>-->
41+
<!-- <a href="configuration-reference.md" summary="YAML configuration syntax and options for all component types">Configuration Reference</a>-->
42+
<!-- <a href="api-reference.md" summary="Process, message, channel, registry, and agent APIs with examples">API Reference</a>-->
43+
<!-- </cards>-->
4444

4545
<cards>
4646
<title>Learning Paths</title>
@@ -79,4 +79,4 @@
7979
</misc>
8080
</section-starting-page>
8181

82-
</topic>
82+
</topic>

‎docs/topics/reference/api-reference/api-agent.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# API: Agent API
2+
3+
<!--
4+
Title: Agent API Reference
5+
TOC: Reference → API Reference → Agent API
6+
Audience: AI developers building agents and tools
7+
Duration: 30-35 minutes reference time
8+
-->
9+
10+
## Purpose
11+
12+
Complete reference for Wippy's Agent API, covering agent creation, tool integration, conversation management, and the agent framework's programmatic interface.
13+
14+
## Content Plan
15+
16+
This reference will document:
17+
18+
1. **Agent Creation and Configuration**
19+
- Programmatic agent definition and instantiation
20+
- Dynamic configuration and runtime modification
21+
- Agent inheritance and trait composition
22+
- Lifecycle management and resource cleanup
23+
24+
2. **Tool Integration and Management**
25+
- Tool registration and discovery
26+
- Function calling and result handling
27+
- Tool delegation and routing
28+
- Custom tool development patterns
29+
30+
3. **Conversation and Memory APIs**
31+
- Conversation state management
32+
- Memory persistence and retrieval
33+
- Context window optimization
34+
- History pruning and archival
35+
36+
4. **Agent Orchestration**
37+
- Multi-agent coordination patterns
38+
- Message routing between agents
39+
- Delegation and handoff mechanisms
40+
- Agent supervision and monitoring
41+
42+
## Implementation Details
43+
44+
### Agent Framework Components:
45+
- **Agent Runtime**: Execution environment and lifecycle
46+
- **Tool System**: Registration, discovery, execution
47+
- **Memory Management**: Persistence, retrieval, optimization
48+
- **Orchestration Layer**: Multi-agent coordination
49+
50+
### API Structure:
51+
- **Core Agent APIs**: Creation, configuration, execution
52+
- **Tool Integration**: Registration, calling, result handling
53+
- **Memory Operations**: Storage, retrieval, management
54+
- **Coordination APIs**: Agent-to-agent communication
55+
56+
### Programming Interface:
57+
- Function signatures and type definitions
58+
- Async/await patterns and error handling
59+
- Resource management and cleanup
60+
- Performance monitoring and optimization
61+
- Integration with process system
62+
63+
### Advanced Features:
64+
- Custom agent types and behaviors
65+
- Plugin architecture for extensions
66+
- Real-time configuration updates
67+
- Distributed agent coordination
68+
- Debugging and introspection tools

‎docs/topics/reference/api-reference/api-message.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# API: Message API
2+
3+
<!--
4+
Title: Message API Reference
5+
TOC: Reference → API Reference → Message API
6+
Audience: Developers working with message-passing patterns
7+
Duration: 15-20 minutes reference time
8+
-->
9+
10+
## Purpose
11+
12+
Complete reference for Wippy's Message API, covering message structures, payload handling, topic management, and communication patterns between processes.
13+
14+
## Content Plan
15+
16+
This reference will document:
17+
18+
1. **Message Structure and Properties**
19+
- Message object structure and metadata
20+
- `message:topic()` - accessing message topics
21+
- `message:payload()` - payload access and unmarshaling
22+
- Message lifecycle and memory management
23+
24+
2. **Payload Handling**
25+
- `payload:data()` - data extraction and type conversion
26+
- Serialization formats and data types
27+
- Binary data and streaming support
28+
- Error handling during deserialization
29+
30+
3. **Topic-based Communication**
31+
- Topic naming conventions and best practices
32+
- Wildcard patterns and routing
33+
- Topic hierarchies and namespacing
34+
- Performance considerations
35+
36+
4. **Message Patterns**
37+
- Fire-and-forget messaging
38+
- Request-response with reply_to
39+
- Broadcast and multicast patterns
40+
- Message ordering guarantees
41+
42+
## Implementation Details
43+
44+
### Message API Components:
45+
- **Message Objects**: Structure, properties, lifecycle
46+
- **Payload Interface**: Data access, type conversion, streaming
47+
- **Topic System**: Naming, routing, pattern matching
48+
- **Communication Patterns**: Synchronous/asynchronous messaging
49+
50+
### Documentation Structure:
51+
- Interface definitions with type signatures
52+
- Usage examples for each method
53+
- Error conditions and handling
54+
- Performance implications
55+
- Integration with channel operations
56+
57+
### Code Examples:
58+
- Basic message sending and receiving
59+
- Payload unmarshaling with error handling
60+
- Topic-based routing implementation
61+
- Complex communication patterns
62+
- Message debugging and inspection

‎docs/topics/reference/api-reference/api-process.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# API: Process API
2+
3+
<!--
4+
Title: Process API Reference
5+
TOC: Reference → API Reference → Process API
6+
Audience: Developers implementing process-based applications
7+
Duration: 20-30 minutes reference time
8+
-->
9+
10+
## Purpose
11+
12+
Comprehensive reference documentation for Wippy's Process API, covering all functions, parameters, return values, and usage patterns for the actor model implementation.
13+
14+
## Content Plan
15+
16+
This reference will include:
17+
18+
1. **Process Lifecycle Management**
19+
- `process.spawn()`, `process.spawn_monitored()`, `process.spawn_linked()`
20+
- Process termination and cancellation
21+
- Process options and configuration
22+
23+
2. **Message Passing Operations**
24+
- `process.send()` - sending messages between processes
25+
- `process.listen()` - creating topic-specific channels
26+
- `process.inbox()` - accessing default inbox
27+
- Message format and serialization
28+
29+
3. **Process Registry Functions**
30+
- `process.registry.register()`, `process.registry.lookup()`
31+
- `process.registry.unregister()`
32+
- Name resolution and discovery
33+
34+
4. **Process Monitoring and Linking**
35+
- `process.link()`, `process.unlink()`
36+
- `process.monitor()`, `process.unmonitor()`
37+
- Event handling and supervision patterns
38+
39+
5. **System Events and Control**
40+
- `process.events()` - system event channel
41+
- Event types: CANCEL, EXIT, LINK_DOWN
42+
- Process options and trap_links configuration
43+
44+
## Implementation Details
45+
46+
### API Categories to Document:
47+
- **Core Process Functions**: Creation, termination, identification
48+
- **Communication APIs**: Message sending, receiving, channels
49+
- **Registry Operations**: Name registration and lookup
50+
- **Supervision APIs**: Linking, monitoring, event handling
51+
- **System Integration**: Events, options, lifecycle management
52+
53+
### For Each Function Document:
54+
- Function signature and parameters
55+
- Return values and error conditions
56+
- Usage examples with full context
57+
- Best practices and common patterns
58+
- Cross-references to related functions
59+
60+
### Code Examples to Include:
61+
- Basic process spawning and communication
62+
- Request-response patterns
63+
- Supervision tree setup
64+
- Error handling and recovery
65+
- Performance considerations

‎docs/topics/reference/api-reference/api-registry.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# API: Registry API
2+
3+
<!--
4+
Title: Registry API Reference
5+
TOC: Reference → API Reference → Registry API
6+
Audience: Developers working with configuration and component management
7+
Duration: 25-30 minutes reference time
8+
-->
9+
10+
## Purpose
11+
12+
Comprehensive reference for Wippy's Registry API, covering component registration, configuration management, and the distributed registry system for versioned metadata.
13+
14+
## Content Plan
15+
16+
This reference will include:
17+
18+
1. **Registry Operations**
19+
- `registry.get()`, `registry.set()`, `registry.delete()`
20+
- `registry.list()`, `registry.search()`
21+
- Namespace management and scoping
22+
- Version control and history
23+
24+
2. **Component Registration**
25+
- Component lifecycle registration
26+
- Dependency resolution and validation
27+
- Metadata management and tagging
28+
- Configuration inheritance patterns
29+
30+
3. **Query and Discovery**
31+
- Component discovery by type and tags
32+
- Dependency graph traversal
33+
- Service location and binding
34+
- Runtime configuration updates
35+
36+
4. **Versioning and History**
37+
- Version management strategies
38+
- Configuration snapshots and rollback
39+
- Change tracking and auditing
40+
- Migration support between versions
41+
42+
## Implementation Details
43+
44+
### Registry System Architecture:
45+
- **Distributed Registry**: Multi-node consistency and replication
46+
- **Versioning Model**: Immutable configurations with history
47+
- **Namespace System**: Hierarchical organization and access control
48+
- **Metadata Framework**: Tags, types, and custom attributes
49+
50+
### API Categories:
51+
- **CRUD Operations**: Create, read, update, delete registry entries
52+
- **Discovery APIs**: Search, filter, and query capabilities
53+
- **Version Management**: History, snapshots, rollback operations
54+
- **System Integration**: Component lifecycle and dependency injection
55+
56+
### Documentation Elements:
57+
- Complete API reference with examples
58+
- Configuration schema definitions
59+
- Best practices for registry organization
60+
- Performance tuning and caching strategies
61+
- Error handling and recovery procedures

‎docs/topics/reference/framework-modules/ref-agent-gen1.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Reference: agent_gen1 Module
2+
3+
<!--
4+
Title: agent_gen1 Module Reference
5+
TOC: Reference → Framework Modules → agent_gen1
6+
Audience: Developers implementing LLM agent runtime
7+
Duration: 30 minutes reference time
8+
-->
9+
10+
## Purpose
11+
12+
Complete reference for the agent_gen1 module, which provides the library for running LLM agents with conversation management, tool calling, delegation capabilities, and token usage tracking.
13+
14+
## Content Plan
15+
16+
This reference will cover:
17+
18+
1. **Agent Runtime Interface**
19+
- Agent instantiation and initialization
20+
- Conversation lifecycle management
21+
- Message processing and response generation
22+
- Resource cleanup and termination
23+
24+
2. **Conversation Management**
25+
- Message history and context window handling
26+
- Token counting and optimization
27+
- Memory pruning and archival strategies
28+
- Context persistence and restoration
29+
30+
3. **Tool Integration System**
31+
- Tool registration and discovery
32+
- Function calling and execution
33+
- Result handling and error management
34+
- Tool delegation and routing
35+
36+
4. **Performance and Monitoring**
37+
- Token usage tracking and optimization
38+
- Response time monitoring
39+
- Error rate tracking and alerting
40+
- Resource usage profiling
41+
42+
## Implementation Details
43+
44+
### Core Runtime Functions:
45+
- Agent instantiation and configuration
46+
- Conversation state management
47+
- Message processing pipeline
48+
- Tool execution coordination
49+
50+
### Conversation Features:
51+
- Multi-turn conversation handling
52+
- Context window management
53+
- Memory optimization strategies
54+
- History persistence patterns
55+
56+
### Tool System:
57+
- Tool calling protocol implementation
58+
- Error handling and retry logic
59+
- Delegation chain execution
60+
- Performance monitoring
61+
62+
### Integration APIs:
63+
- LLM provider abstraction
64+
- Configuration system integration
65+
- Metrics collection and reporting
66+
- Debugging and introspection hooks
67+
68+
### Advanced Capabilities:
69+
- Streaming response handling
70+
- Concurrent tool execution
71+
- Resource pool management
72+
- Fault tolerance and recovery

0 commit comments

Comments
 (0)