# Building with Co-author

## Building with Co-author

Co-author is your AI-powered assistant for building knowledge graphs. Whether you're starting from scratch with business documentation or refining an existing graph, Co-author helps you get there faster.

{% hint style="info" icon="rectangle-beta" %}
Co-author is currently in beta. It may contain bugs, are subject to change and are not covered by our platform SLAs. Your feedback can help shape development.
{% endhint %}

### Getting Started

Co-author supports two workflows depending on where you are in the build process:

#### Starting a new graph

From the Rainbird Studio home page or from a new graph, select **Generate from Documentation**, provide a name for your graph, explain what you would like to be built and upload relevant documentation. See below for further information on [document guidelines](#documentation-guidelines) and [best practice](#best-practice).

Co-author will analyse your documentation in depth, build a structured first draft and save it as a new knowledge graph. Your prompt and documentation will then be available in the Co-author chat panel so you can continue refining seamlessly.

If you need support with writing a detailed prompt that articulates the details and nuances of your domain then consider using [Consult](https://docs.rainbird.ai/rainbird/rainbird-labs/consult). This uses knowledge elicitation techniques to extract tacit knowledge and information that may not be available in documentation alone.

{% embed url="<https://www.loom.com/share/fb644249d8cf4c81925013dc913c0853>" %}

#### Refining an existing graph

Within the Rainbird Studio, open the Co-author chat panel in any knowledge graph and write your instructions. Learn more about [Co-author use cases](#co-author-use-cases) below.

Updates will be applied to the graph and an explanation of the change provided in the Co-author chat panel.

It is advised to create a snapshot of your graph by versioning it prior to changes, as undo functionality is not currently available.

{% embed url="<https://www.loom.com/share/7e468a266ed745c5ab73351caab66bed>" %}

### Documentation guidelines

When using documentation to start a new graph, or refining an existing one, the following guidelines will help Co-author produce the best results.

#### Supported formats and limits

* Supported formats include TXT, PDF & CSV.
* Maximum of 6 files can be uploaded.
* Only text is processed; images will be removed before processing.
* Document size may impact the generated knowledge graph. As an approximation, the total of the prompt and any documentation should be less than 50,000 words (approximately 90 pages of text).

#### Best practice

To improve the accuracy of the knowledge graph produced, please consider some of these tips:

1. **Focus on outcomes:** Ensure your prompt and/or document is outcome-focused. Remove any unnecessary introductions or preamble, and avoid including descriptive or scene-setting content that doesn't contribute to decision-making.
2. **Ensure clarity and completeness:** Make sure the information provided is clear and complete. As a general rule of thumb, the information needs to be good enough for a human without domain knowledge to build from.
3. **Simplify the formatting:** Minimise complex formatting. Remove paragraph and chapter numbering, convert multi-column text into a single, well-structured and fluid document.
4. **Modularise content:** If needed, break your document into smaller, manageable segments. Each part should describe a specific piece of expertise. This approach often leads to better results when applied iteratively.

The following types of documents should work well:

1. Standard Operating Procedures (SOPs) with clear process flows ✅
2. Regulatory compliance documents with explicit requirements ✅
3. Technical specifications with clear dependencies and constraints ✅
4. Policy manuals with well-defined rules and conditions ✅
5. Service Level Agreements (SLAs) with specific criteria and thresholds ✅
6. Decision trees and decision matrices in documented form ✅

Documents that are less likely to perform well include:

1. Documents that are highly visual, with meaning held in graphs, charts or complex tables ❌
2. Academic-style papers with multiple column layouts, complex mathematical calculations or references and citations that break up the main text flow ❌
3. Scanned documents with poor OCR quality ❌
4. Documents with implicit knowledge assumptions ❌
5. Highly contextual or situational guidelines ❌
6. Documentation with undefined jargon or acronyms ❌

{% hint style="success" %}
**Best practice reminder**

* **Focus on outcomes:** Keep the content tightly aligned to a clear goal or decision — cut fluff and background narrative.
* **Ensure clarity and completeness:** Write so someone without domain expertise could act on it confidently.
* **Simplify formatting:** Use clean, single-column text with minimal structure — avoid numbering and visual complexity.
* **Modularise content:** Split large documents into smaller, focused parts that each describe a distinct process or rule.
* **Use structured, explicit sources:** SOPs, policies, SLAs, specs, and decision frameworks work best — avoid visual, academic, or vague materials.
  {% endhint %}

### Co-author use cases

Use Co-author to help you understand, refine and expand your knowledge graphs.

Below are some examples of what you can ask Co-author to do using the different modes available.

#### Updating the graph (using the default 'Edit' mode)

* **Quickly add multiple instances:** "Add instances for every country in Europe"
* **Create facts:** "Update the graph to include facts stating the national languages for every country in Europe"
* **Create test data:** "Add facts for John, Paul, George and Ringo, using different data for each person"
* **Iteratively expand the knowledge graph:** "Expand the graph so it also factors in the native language spoken by the person's parents."
* **Update question wording:** "Can you improve the question wording for all relationships that can ask questions?"
* **Copy rules between relationships:** "Copy the rule on relationship \[relationship name] onto \[relationship name], ensuring it is updated to reflect the new relationship"

#### Searching the graph (using the 'Ask' mode)

* "What relationships can I query?"
* "Can you list all relationships that can ask questions?"
* "Which relationships are in a group?"
* "Can you list all date concepts?"

#### Explaining the graph (using the 'Ask' mode)

* "Can you explain the rules on the \[name] relationship?"
* "Can you explain what this graph does?"

### Versioning

It is recommended to version your knowledge map between Co-author requests, including a comment of the changes introduced.

This provides an opportunity to easily restore an older version if you want to undo a Co-author change. Information on versioning can be found in the [Academy](https://academy.rainbird.ai/learningpath/rainbird-authoring-tools-versioning).

{% hint style="info" %}
Versions can only be created when there are no errors in the knowledge map. There may be some known errors introduced by Co-author, which are mentioned below.
{% endhint %}

### Important Information

#### Data Security

Co-author uses third-party AI services (Anthropic hosted in AWS Bedrock). However this data will be encrypted in transit and at rest by AWS Bedrock and will not be used for training purposes. Data will be processed within the EU and continues to be ISO27001 compliant.

#### Limitations

* Token limits apply. For large content and/or large knowledge graphs, limits may be reached and incomplete RBLang returned resulting in error.
* Service may be interrupted during peak periods.
* Varying behaviour: LLMs are not deterministic so you will likely see different responses when testing the same content.
* Map layout: When starting a new graph, concepts will auto-layout. When updating an existing graph, new concepts will be placed in the centre and require manually rearranging.
* RBLang errors: whilst we continue to make improvements, there are some common errors that may be introduced. You can ask Co-author to fix some of these (copy and paste the error to Co-author), but some may need to be fixed manually. Some of these can be fixed in the Editor UI, whilst others will require fixing directly in RBLang (accessed via the \</> code panel).

#### Common errors

1. **Rules that reference instances that don't exist**
   * Identify the relationship of this rule, identify the concept it's attached to then add the instance to this concept.
2. **Incorrect use of variables in the rule header**
   * You may see `Subject="%PERSON"` in the rule header (the start of the rule). This is invalid, as custom variables can only be used in conditions. Either change this to `%S` (for the subject) or `%O` (for the object), or remove any subject/object containing a variable from the rule header, as the rule will operate as intended without it being declared. It may also have used the incorret variable in the conditions below, when it should use the specially designated variables of `%S` for the subject or `%O` for the object. These will also require updating.
3. **Relationships referencing concepts that don't exist**
   * Often these tend to be called something generic like String, Date, Number or Truth. You will need to review the graph, determine what the concept should be called, create one with this name then update the relationship to refer to your new concept.
4. **Invalid expressions**
   * Unsupported expressions can sometimes be generated, which can be manually fixed in the UI. Use our [documentation](https://docs.rainbird.ai/rainbird/knowledge-modelling/modelling-features/relationships/rules/expressions-list) to help create a valid expression. Where an expression contains multiple OR conditions, this can sometimes indicate the rule needs to be split into multiple rules. You can duplicate the rule and modify them, or prompt Co-author to separate these rules into distinctive rules.

Once fixed and you can save successfully, create a version of this so you can return to it if required.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.rainbird.ai/rainbird/knowledge-modelling/modelling-features/building-with-co-author.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.