Readme Edits | Just cleanup edits

docs/design/01 - Programming Model.md

@@ -6,23 +6,27 @@ The programming model is basically publish-subscribe. Agents subscribe to events
 
 ## Events Delivered as CloudEvents
 
-Each event in the system is defined using the [CloudEvents Specification](https://cloudevents.io/). This allows for a common event format that can be used across different systems and languages.  In CloudEvents, each event has a Context Attributes that must unique *id* (eg a UUID) a *source* (a unique urn or path), a *type* (the namespace of the event - prefixed with a reverse-DNS name. The prefixed domain dictates the organization which defines the semantics of this event type: e.g *com.github.pull_request.opened* or
-*com.example.object.deleted.v2*), and optionally fields describing the data schema/content-type or extensions.
+Each event in the system is defined using the [CloudEvents Specification](https://cloudevents.io/). This allows for a common event format that can be used across different systems and languages. In CloudEvents, each event has "Context Attributes" that must include:
+
+1. _*id*_ - A unique id (eg. a UUID).
+2. _*source*_ - A URI or URN indicating the event's origin.
+3. _*type*_ - The namespace of the event - prefixed with a reverse-DNS name.
+   - The prefixed domain dictates the organization which defines the semantics of this event type: e.g `_com.github.pull_request.opened_` or `_com.example.object.deleted.v2_`), and optionally fields describing the data schema/content-type or extensions.
 
 ## Event Handlers
 
-Each agent has a set of event handlers, that are bound to a specific match against a CloudEvents *type*. Event Handlers could match against an exact type or match for a pattern of events of a particular level in the type heirarchy (eg: *com.Microsoft.AutoGen.Agents.System.\** for all Events in the *System* namespace) Each event handler is a function that can change state, call models, access memory, call external tools, emit other events, and flow data to/from other systems. Each event handler can be a simple function or a more complex function that uses a state machine or other control logic.
+Each agent has a set of event handlers, that are bound to a specific match against a CloudEvents _*type*_. Event Handlers could match against an exact type or match for a pattern of events of a particular level in the type heirarchy (eg: `\*com.Microsoft.AutoGen.Agents.System.\**` for all Events in the `*System\*` namespace) Each event handler is a function that can change state, call models, access memory, call external tools, emit other events, and flow data to/from other systems. Each event handler can be a simple function or a more complex function that uses a state machine or other control logic.
 
 ## Orchestrating Agents
 
-If is possible to build a functional and scalable agent system that only reacts to external events. In many cases, however, you will want to orchestrate the agents to achieve a specific goal or follow a pre-determined workflow. In this case, you will need to build an orchestrator agent that manages the flow of events between agents.
+It is _possible_ to build a functional and scalable agent system that only reacts to external events. In many cases, however, you will want to orchestrate the agents to achieve a specific goal or follow a pre-determined workflow. In this case, you will need to build an orchestrator agent that manages the flow of events between agents.
 
 ## Built-in Event Types
 
 The AutoGen system comes with a set of built-in event types that are used to manage the system. These include:
 
-* System Events - Events that are used to manage the system itself. These include events for starting and stopping the Agents, sending messages to all agents, and other system-level events.
-* ? insert other types here ?
+- _*System Events*_ - Events that are used to manage the system itself. These include events for starting and stopping the Agents, sending messages to all agents, and other system-level events.
+- ? insert other types here ?
 
 ## Agent Contracts
 

docs/design/02 - Topics.md

@@ -6,7 +6,7 @@ This document describes the semantics and components of publishing messages and
 
 Topics are used as the primitive to manage which agents receive a given published message. Agents subscribe to topics. There is an application defined mapping from topic to agent instance.
 
-These concepts intentionally map to the [CloudEvents](https://cloudevents.io/) specification. This allows for easy integration with existing systems and tools.
+These concepts intentionally maps to the [CloudEvents](https://cloudevents.io/) specification. This allows for easy integration with existing systems and tools.
 
 ### Non-goals
 
@@ -17,16 +17,16 @@ This document does not specify RPC/direct messaging
 A topic is identified by two components (called a `TopicId`):
 
 - [`type`](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type) - represents the type of event that occurs, this is static and defined in code
-    - SHOULD use reverse domain name notation to avoid naming conflicts. For example: `com.example.my-topic`.
+  - SHOULD use reverse domain name notation to avoid naming conflicts. For example: `com.example.my-topic`.
 - [`source`](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source-1) - represents where the event originated from, this is dynamic and based on the message itself
-    - SHOULD be a URI
+  - SHOULD be a URI
 
 Agent instances are identified by two components (called an `AgentId`):
 
 - `type` - represents the type of agent, this is static and defined in code
-    - MUST be a valid identifier as defined [here](https://docs.python.org/3/reference/lexical_analysis.html#identifiers) except that only the ASCII range is allowed
+  - MUST be a valid identifier as defined [here](https://docs.python.org/3/reference/lexical_analysis.html#identifiers) except that only the ASCII range is allowed
 - `key` - represents the instance of the agent type for the key
-    - SHOULD be a URI
+  - SHOULD be a URI
 
 For example: `GraphicDesigner:1234`
 

docs/design/03 - worker-protocol.md

@@ -22,15 +22,15 @@ Agents are never explicitly created or destroyed. When a request is received for
 
 ## Worker protocol flow
 
-The worker protocol has three phases, following the lifetime of the worker: initiation, operation, and termination.
+The worker protocol has three phases, following the lifetime of the worker: initialization, operation, and termination.
 
 ### Initialization
 
 When the worker process starts, it initiates a connection to a service process, establishing a bi-directional communication channel which messages are passed across.
 Next, the worker issues zero or more `RegisterAgentType(name: str)` messages, which tell the service the names of the agents which it is able to host.
 
-* TODO: What other metadata should the worker give to the service?
-* TODO: Should we give the worker a unique id which can be used to identify it for its lifetime? Should we allow this to be specified by the worker process itself?
+- TODO: What other metadata should the worker give to the service?
+- TODO: Should we give the worker a unique id which can be used to identify it for its lifetime? Should we allow this to be specified by the worker process itself?
 
 ### Operation
 
@@ -40,12 +40,12 @@ The worker maintains a _catalog_ of locally active agents: a mapping from agent
 If a message arrives for an agent which does not have a corresponding entry in the catalog, the worker activates a new instance of that agent and inserts it into the catalog.
 The worker dispatches the message to the agent:
 
-* For an `Event`, the agent processes the message and no response is generated.
-* For an `RpcRequest` message, the agent processes the message and generates a response of type `RpcResponse`. The worker routes the response to the original sender.
+- For an `Event`, the agent processes the message and no response is generated.
+- For an `RpcRequest` message, the agent processes the message and generates a response of type `RpcResponse`. The worker routes the response to the original sender.
 
 The worker maintains a mapping of outstanding requests, identified by `RpcRequest.id`, to a promise for a future `RpcResponse`.
-When an `RpcResponse` is received, the worker finds the corresponding request id and fulfils the promise using that response.
-If no response is received in a specified time frame (eg, 30s), the worker breaks the promise with a timeout error.
+When an `RpcResponse` is received, the worker finds the corresponding request id and fulfills the promise using that response.
+If no response is received in a specified time frame (eg. `30s`), the worker breaks the promise with a timeout error.
 
 ### Termination
 

docs/design/04 - Agent and Topic ID Specs.md

@@ -8,40 +8,40 @@ This document describes the structure, constraints, and behavior of Agent IDs an
 
 #### type
 
-* Type: `string`
-* Description: The agent type is not an agent class. It associates an agent with a specific factory function, which produces instances of agents of the same agent `type`. For example, different factory functions can produce the same agent class but with different constructor perameters.
-* Constraints: UTF8 and only contain alphanumeric letters (a-z) and (0-9), or underscores (_). A valid identifier cannot start with a number, or contain any spaces.
-* Examples:
-    * `code_reviewer`
-    * `WebSurfer`
-    * `UserProxy`
+- Type: `string`
+- Description: The agent type is not an agent class. It associates an agent with a specific factory function, which produces instances of agents of the same agent `type`. For example, different factory functions can produce the same agent class but with different constructor perameters.
+- Constraints: UTF8 and only contain alphanumeric letters (a-z) and (0-9), or underscores (\_). A valid identifier cannot start with a number, or contain any spaces.
+- Examples:
+  - `code_reviewer`
+  - `WebSurfer`
+  - `UserProxy`
 
 #### key
 
-* Type: `string`
-* Description: The agent key is an instance identifier for the given agent `type`
-* Constraints: UTF8 and only contain characters between (inclusive) ascii 32 (space) and 126 (~).
-* Examples:
-    * `default`
-    * A memory address
-    * a UUID string
+- Type: `string`
+- Description: The agent key is an instance identifier for the given agent `type`
+- Constraints: UTF8 and only contain characters between (inclusive) ascii 32 (space) and 126 (~).
+- Examples:
+  - `default`
+  - A memory address
+  - a UUID string
 
 ## Topic ID
 
 ### Required Attributes
 
 #### type
 
-* Type: `string`
-* Description: topic type is usually defined by application code to mark the type of messages the topic is for.
-* Constraints: UTF8 and only contain alphanumeric letters (a-z) and (0-9), or underscores (_). A valid identifier cannot start with a number, or contain any spaces.
-* Examples:
-    * `GitHub_Issues`
+- Type: `string`
+- Description: Topic type is usually defined by application code to mark the type of messages the topic is for.
+- Constraints: UTF8 and only contain alphanumeric letters (a-z) and (0-9), or underscores (\_). A valid identifier cannot start with a number, or contain any spaces.
+- Examples:
+  - `GitHub_Issues`
 
 #### source
 
-* Type: `string`
-* Description: Topic source is the unique identifier for a topic within a topic type. It is typically defined by application data.
-* Constraints: UTF8 and only contain characters between (inclusive) ascii 32 (space) and 126 (~).
-* Examples:
-    * `github.com/{repo_name}/issues/{issue_number}`
+- Type: `string`
+- Description: Topic source is the unique identifier for a topic within a topic type. It is typically defined by application data.
+- Constraints: UTF8 and only contain characters between (inclusive) ascii 32 (space) and 126 (~).
+- Examples:
+  - `github.com/{repo_name}/issues/{issue_number}`