jarviscore-framework 0.2.1__py3-none-any.whl → 0.3.1__py3-none-any.whl

jarviscore/docs/API_REFERENCE.md

@@ -14,7 +14,13 @@ Complete API documentation for JarvisCore framework components.
    - [AutoAgent](#autoagent)
    - [Custom Profile](#custom-profile)
    - [CustomAgent](#customagent)
-3. [Execution Components](#execution-components)
+3. [P2P Communication (v0.3.0)](#p2p-communication-v030)
+   - [PeerClient](#peerclient)
+   - [IncomingMessage](#incomingmessage)
+   - [Cognitive Discovery](#cognitive-discovery)
+4. [Integrations (v0.3.0)](#integrations-v030)
+   - [JarvisLifespan](#jarvislifespan)
+5. [Execution Components](#execution-components)
    - [CodeGenerator](#codegenerator)
    - [SandboxExecutor](#sandboxexecutor)
    - [AutoRepair](#autorepair)
@@ -557,6 +563,280 @@ See [CustomAgent Guide](CUSTOMAGENT_GUIDE.md) for P2P and distributed mode detai
 
 ---
 
+#### P2P Message Handlers
+
+CustomAgent includes built-in P2P message handlers:
+
+#### `async on_peer_request(msg) -> dict`
+
+Handle incoming request messages. Return value is sent back to requester.
+
+```python
+async def on_peer_request(self, msg):
+    query = msg.data.get("question", "")
+    result = self.process(query)
+    return {"response": result, "status": "success"}
+```
+
+**Parameters:**
+- `msg` (IncomingMessage): Incoming message with `data`, `sender`, `correlation_id`
+
+**Returns:** dict - Response sent back to requester (if `auto_respond=True`)
+
+---
+
+#### `async on_peer_notify(msg) -> None`
+
+Handle broadcast notifications. No return value needed.
+
+```python
+async def on_peer_notify(self, msg):
+    event_type = msg.data.get("type")
+    if event_type == "status_update":
+        self.handle_status(msg.data)
+```
+
+**Parameters:**
+- `msg` (IncomingMessage): Incoming notification message
+
+**Returns:** None
+
+---
+
+#### `async on_error(error, msg) -> None`
+
+Handle errors during message processing.
+
+```python
+async def on_error(self, error, msg):
+    self._logger.error(f"Error processing message: {error}")
+```
+
+**Parameters:**
+- `error` (Exception): The exception that occurred
+- `msg` (IncomingMessage, optional): The message being processed
+
+---
+
+#### Configuration Attributes
+
+- `listen_timeout` (float): Seconds to wait for messages in run loop (default: 1.0)
+- `auto_respond` (bool): Automatically send on_peer_request return value (default: True)
+
+---
+
+#### Self-Registration Methods
+
+#### `async join_mesh(seed_nodes, advertise_endpoint=None)`
+
+Join an existing mesh without central orchestrator.
+
+```python
+await agent.join_mesh(
+    seed_nodes="10.0.0.1:7950,10.0.0.2:7950",
+    advertise_endpoint="my-pod:7950"
+)
+```
+
+**Parameters:**
+- `seed_nodes` (str): Comma-separated list of seed node addresses
+- `advertise_endpoint` (str, optional): Address for other nodes to reach this agent
+
+---
+
+#### `async leave_mesh()`
+
+Gracefully leave the mesh network.
+
+```python
+await agent.leave_mesh()
+```
+
+---
+
+## P2P Communication (v0.3.0)
+
+### PeerClient
+
+Client for peer-to-peer communication, available as `self.peers` on agents.
+
+#### Class: `PeerClient`
+
+**Methods:**
+
+#### `get_cognitive_context() -> str`
+
+Generate LLM-ready text describing available peers.
+
+```python
+if self.peers:
+    context = self.peers.get_cognitive_context()
+    # Returns:
+    # "Available Peers:
+    # - analyst (capabilities: analysis, data_interpretation)
+    #   Use ask_peer with role="analyst" for analysis tasks
+    # - researcher (capabilities: research, web_search)
+    #   Use ask_peer with role="researcher" for research tasks"
+```
+
+**Returns:** str - Human-readable peer descriptions for LLM prompts
+
+---
+
+#### `list() -> List[PeerInfo]`
+
+Get list of connected peers.
+
+```python
+peers = self.peers.list()
+for peer in peers:
+    print(f"{peer.role}: {peer.capabilities}")
+```
+
+**Returns:** List of PeerInfo objects
+
+---
+
+#### `as_tool() -> PeerTool`
+
+Get peer tools for LLM tool use.
+
+```python
+tools = self.peers.as_tool()
+result = await tools.execute("ask_peer", {"role": "analyst", "question": "..."})
+```
+
+**Available Tools:**
+- `ask_peer` - Send request and wait for response
+- `broadcast` - Send notification to all peers
+- `list_peers` - List available peers
+
+---
+
+#### `async receive(timeout) -> IncomingMessage`
+
+Receive next message (for CustomAgent manual loops).
+
+```python
+msg = await self.peers.receive(timeout=0.5)
+if msg and msg.is_request:
+    await self.peers.respond(msg, {"result": "..."})
+```
+
+---
+
+#### `async respond(msg, data) -> None`
+
+Respond to a request message.
+
+```python
+await self.peers.respond(msg, {"status": "success", "result": data})
+```
+
+---
+
+### IncomingMessage
+
+Message received from a peer.
+
+#### Class: `IncomingMessage`
+
+**Attributes:**
+- `data` (dict): Message payload
+- `sender_role` (str): Role of sending agent
+- `sender_id` (str): ID of sending agent
+- `is_request` (bool): True if this is a request expecting response
+- `is_notify` (bool): True if this is a notification
+
+```python
+async def on_peer_request(self, msg):
+    print(f"From: {msg.sender_role}")
+    print(f"Data: {msg.data}")
+    return {"received": True}
+```
+
+---
+
+### Cognitive Discovery
+
+Dynamic peer awareness for LLM prompts.
+
+**Pattern:**
+
+```python
+class MyAgent(CustomAgent):
+    def get_system_prompt(self) -> str:
+        base = "You are a helpful assistant."
+
+        # Dynamically add peer context
+        if self.peers:
+            peer_context = self.peers.get_cognitive_context()
+            return f"{base}\n\n{peer_context}"
+
+        return base
+```
+
+**Benefits:**
+- No hardcoded agent names in prompts
+- Automatically updates when peers join/leave
+- LLM always knows current capabilities
+
+---
+
+## Integrations (v0.3.0)
+
+### JarvisLifespan
+
+FastAPI lifespan context manager for automatic agent lifecycle management.
+
+#### Class: `JarvisLifespan`
+
+```python
+from jarviscore.integrations.fastapi import JarvisLifespan
+
+app = FastAPI(lifespan=JarvisLifespan(agent, mode="p2p"))
+```
+
+**Parameters:**
+- `agent`: CustomAgent instance (or list of agents)
+- `mode` (str): "p2p" or "distributed"
+- `bind_port` (int, optional): P2P port (default: 7950)
+- `seed_nodes` (str, optional): Comma-separated seed node addresses
+
+**Example:**
+
+```python
+from fastapi import FastAPI
+from jarviscore.profiles import CustomAgent
+from jarviscore.integrations.fastapi import JarvisLifespan
+
+
+class ProcessorAgent(CustomAgent):
+    role = "processor"
+    capabilities = ["processing"]
+
+    async def on_peer_request(self, msg):
+        return {"result": "processed"}
+
+
+agent = ProcessorAgent()
+app = FastAPI(lifespan=JarvisLifespan(agent, mode="p2p", bind_port=7950))
+
+
+@app.post("/process")
+async def process(data: dict):
+    # Agent is already running and connected to mesh
+    return {"status": "ok"}
+```
+
+**Handles:**
+- Agent setup and teardown
+- Mesh initialization
+- Background run loop (runs agent.run())
+- Graceful shutdown
+
+---
+
 ## Execution Components
 
 ### CodeGenerator
@@ -1140,6 +1420,6 @@ async def execute_task(self, task: Dict[str, Any]) -> Dict[str, Any]:
 
 ## Version
 
-API Reference for JarvisCore v0.2.1
+API Reference for JarvisCore v0.3.1
 
-Last Updated: 2026-01-23
+Last Updated: 2026-01-29

jarviscore/docs/CHANGELOG.md

@@ -0,0 +1,139 @@
+# Changelog
+
+All notable changes to JarvisCore Framework will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.3.1] - 2026-02-02
+
+### Breaking Changes
+
+#### ListenerAgent Removed
+- **ListenerAgent has been merged into CustomAgent**
+- Migration is simple - just change the import:
+  ```python
+  # Before
+  from jarviscore.profiles import ListenerAgent
+  class MyAgent(ListenerAgent): ...
+
+  # After
+  from jarviscore.profiles import CustomAgent
+  class MyAgent(CustomAgent): ...
+  ```
+- All handler methods work exactly the same way
+- No other code changes required
+
+### Changed
+
+#### CustomAgent Now Includes P2P Handlers
+- `on_peer_request(msg)` - Handle incoming requests (return value sent as response)
+- `on_peer_notify(msg)` - Handle fire-and-forget notifications
+- `on_error(error, msg)` - Handle errors during message processing
+- `run()` - Built-in listener loop (no need to write your own)
+- Configuration: `listen_timeout`, `auto_respond`
+
+#### Simplified Profile Architecture
+| Before (v0.3.0) | After (v0.3.1) |
+|-----------------|----------------|
+| AutoAgent + CustomAgent + ListenerAgent | AutoAgent + CustomAgent |
+| "Which profile do I use?" confusion | Clear: AutoAgent (LLM) or CustomAgent (your code) |
+
+### Documentation
+- README.md updated with unified CustomAgent examples
+- GETTING_STARTED.md rewritten with framework integration patterns
+- CUSTOMAGENT_GUIDE.md updated (ListenerAgent sections removed)
+- Added async-first framework guidance (FastAPI, aiohttp, Flask patterns)
+
+---
+
+## [0.3.0] - 2026-01-29
+
+### Added
+
+#### ListenerAgent Profile
+- New `ListenerAgent` class for handler-based P2P communication
+- `on_peer_request(msg)` handler for incoming requests
+- `on_peer_notify(msg)` handler for broadcast notifications
+- No more manual `run()` loops required for simple P2P agents
+
+#### FastAPI Integration
+- `JarvisLifespan` context manager for 3-line FastAPI integration
+- Automatic agent lifecycle management (setup, run, teardown)
+- Support for both `p2p` and `distributed` modes
+- Import: `from jarviscore.integrations.fastapi import JarvisLifespan`
+
+#### Cognitive Discovery
+- `peers.get_cognitive_context()` generates LLM-ready peer descriptions
+- Dynamic peer awareness - no more hardcoded agent names in prompts
+- Auto-updates when peers join or leave the mesh
+
+#### Cloud Deployment
+- `agent.join_mesh(seed_nodes)` for self-registration without central orchestrator
+- `agent.leave_mesh()` for graceful departure
+- `agent.serve_forever()` for container deployments
+- `RemoteAgentProxy` for automatic cross-node agent visibility
+- Environment variable support:
+  - `JARVISCORE_SEED_NODES` - comma-separated seed node addresses
+  - `JARVISCORE_MESH_ENDPOINT` - advertised endpoint for this agent
+  - `JARVISCORE_BIND_PORT` - P2P port
+
+### Changed
+
+- Documentation restructured with before/after comparisons
+- CUSTOMAGENT_GUIDE.md expanded with v0.3.0 features
+- API_REFERENCE.md updated with new classes and methods
+
+### Developer Experience
+
+| Before (v0.2.x) | After (v0.3.0) |
+|-----------------|----------------|
+| Manual `run()` loops with `receive()`/`respond()` | `ListenerAgent` with `on_peer_request()` handlers |
+| ~100 lines for FastAPI integration | 3 lines with `JarvisLifespan` |
+| Hardcoded peer names in LLM prompts | Dynamic `get_cognitive_context()` |
+| Central orchestrator required | Self-registration with `join_mesh()` |
+
+---
+
+## [0.2.1] - 2026-01-23
+
+### Fixed
+- P2P message routing stability improvements
+- Workflow engine dependency resolution edge cases
+
+---
+
+## [0.2.0] - 2026-01-15
+
+### Added
+- CustomAgent profile for integrating existing agent code
+- P2P mode for direct agent-to-agent communication
+- Distributed mode combining workflow engine + P2P
+- `@jarvis_agent` decorator for wrapping existing classes
+- `wrap()` function for wrapping existing instances
+- `JarvisContext` for workflow context access
+- Peer tools: `ask_peer`, `broadcast`, `list_peers`
+
+### Changed
+- Mesh now supports three modes: `autonomous`, `p2p`, `distributed`
+- Agent base class now includes P2P support
+
+---
+
+## [0.1.0] - 2026-01-01
+
+### Added
+- Initial release
+- AutoAgent profile with LLM-powered code generation
+- Workflow engine with dependency management
+- Sandbox execution (local and remote)
+- Auto-repair for failed code
+- Internet search integration (DuckDuckGo)
+- Multi-provider LLM support (Claude, OpenAI, Azure, Gemini)
+- Result storage and code registry
+
+---
+
+*JarvisCore Framework - Build autonomous AI agents with P2P mesh networking.*

jarviscore/docs/CONFIGURATION.md

@@ -766,6 +766,6 @@ LOG_DIRECTORY=/tmp/jarviscore-logs
 
 ## Version
 
-Configuration Guide for JarvisCore v0.2.1
+Configuration Guide for JarvisCore v0.3.1
 
 Last Updated: 2026-01-23