doc: v1.0 docs

Signed-off-by: Diwank Singh Tomer <[email protected]>

.gitmodules

@@ -0,0 +1,6 @@
+[submodule "sdks/python-sdk"]
+	path = sdks/python-sdk
+	url = [email protected]:julep-ai/python-sdk.git
+[submodule "sdks/node-sdk"]
+	path = sdks/node-sdk
+	url = [email protected]:julep-ai/node-sdk.git

docs/explanation/chat_features.md

@@ -0,0 +1,68 @@
+# Chat Features in Julep
+
+Julep provides a robust chat system with various features for dynamic interaction with agents. Here's an overview of the key components and functionalities:
+
+## Chat Input
+
+When sending a request to the chat endpoint, you can include:
+
+1. **Messages**: An array of input messages representing the conversation so far.
+2. **Tools**: (Advanced) Additional tools provided for this specific interaction.
+3. **Tool Choice**: Specifies which tool the agent should use.
+4. **Memory Access Options**: Controls how the session accesses history and memories.
+5. **Chat Settings**: Various settings to control the behavior of the chat.
+
+## Chat Settings
+
+Chat settings allow fine-grained control over the generation process:
+
+- `model`: Identifier of the model to be used.
+- `stream`: Indicates if the server should stream the response as it's generated.
+- `stop`: Up to 4 sequences where the API will stop generating further tokens.
+- `seed`: For deterministic sampling.
+- `max_tokens`: The maximum number of tokens to generate.
+- `logit_bias`: Modify the likelihood of specified tokens appearing in the completion.
+- `response_format`: Control the format of the response (e.g., JSON object).
+- `agent`: Agent ID to use (for multi-agent sessions).
+
+Additional settings include `temperature`, `top_p`, `frequency_penalty`, and `presence_penalty`.
+
+## Chat Response
+
+The chat response can be either streamed or returned as a complete message:
+
+1. **Streamed Response**: 
+   - Content-Type: `text/event-stream`
+   - Body: A stream of `ChatOutputChunk` objects.
+
+2. **Complete Response**:
+   - Content-Type: `application/json`
+   - Body: A `MessageChatResponse` object containing the full generated message(s).
+
+Both response types include:
+- `usage`: Token usage statistics.
+- `jobs`: Background job IDs spawned from this interaction.
+- `docs`: Documents referenced for this request (for citation purposes).
+
+## Finish Reasons
+
+The API provides information about why the model stopped generating tokens:
+
+- `stop`: Natural stop point or provided stop sequence reached.
+- `length`: Maximum number of tokens specified in the request was reached.
+- `content_filter`: Content was omitted due to a flag from content filters.
+- `tool_calls`: The model called a tool.
+
+## Advanced Features
+
+1. **Tool Integration**: The chat API allows for the use of tools, enabling the agent to perform actions or retrieve information during the conversation.
+
+2. **Multi-agent Sessions**: You can specify different agents within the same session using the `agent` parameter in the chat settings.
+
+3. **Response Formatting**: Control the output format, including options for JSON responses with specific schemas.
+
+4. **Memory and Recall**: Configure how the session accesses and stores conversation history and memories.
+
+5. **Document References**: The API returns information about documents referenced during the interaction, useful for providing citations or sources.
+
+These features provide developers with a powerful and flexible system for creating sophisticated, context-aware chat interactions that integrate seamlessly with other Julep components.

docs/explanation/context_overflow.md

@@ -0,0 +1,20 @@
+# Context Overflow Handling in Julep
+
+Julep provides mechanisms to handle scenarios where the context size grows beyond the `token_budget` or the model's input limit. The behavior is determined by the `context_overflow` setting:
+
+1. `null` (default): 
+   - Raises an exception
+   - The client is responsible for creating a new session or clearing the history for the current one
+
+2. `"truncate"`: 
+   - Truncates the context from the top, except for the system prompt
+   - Continues truncating until the size falls below the budget
+   - Raises an error if the system prompt and last message combined exceed the budget
+
+3. `"adaptive"`: 
+   - When the context size reaches 75% of the `token_budget`, a background task is created
+   - This task compresses the information by summarizing, merging, and clipping messages in the context
+   - Operates on a best-effort basis
+   - Requests might fail if the context wasn't compressed enough or on time
+
+By offering these options, Julep allows developers to choose the most appropriate strategy for handling context overflow in their applications, balancing between maintaining conversation history and staying within model limits.

docs/explanation/core_concepts.md

@@ -0,0 +1,46 @@
+# Core Concepts in Julep
+
+Julep is a powerful backend system for managing agent execution. It provides several key components that work together to create flexible and intelligent applications. Here are the core concepts:
+
+## Agent
+
+An Agent in Julep is the main orchestrator of your application. Agents are backed by foundation models like GPT4 or Claude and use interaction history to determine their next actions. Key features include:
+
+- Long-lived interactions in sessions
+- Integration with system or user-defined tools
+- Access to agent-level documents for auto-retrieval
+- Ability to define and execute multi-step workflows (tasks)
+
+## User
+
+Users in Julep can be associated with sessions. They are used to scope memories formed by agents and can hold metadata for reference in sessions or task executions.
+
+## Session
+
+Sessions are the main workhorse for Julep apps:
+- They facilitate interactions with agents
+- Each session maintains its own context
+- Can have one or more agents and zero or more users
+- Allows control over context overflow handling
+
+## Tool
+
+Tools in Julep are programmatic interfaces that foundation models can "call" with inputs to achieve a goal. They can be:
+1. User-defined functions
+2. System tools (upcoming)
+3. Built-in integrations (upcoming)
+4. Webhooks & API calls (upcoming)
+
+## Doc
+
+Docs are collections of text snippets (with planned image support) indexed into a built-in vector database. They can be scoped to an agent or a user and are automatically recalled in sessions when relevant.
+
+## Task
+
+Tasks in Julep are Github Actions-style workflows that define long-running, multi-step actions. They allow for complex operations by defining steps and have access to all Julep integrations.
+
+## Execution
+
+An Execution is an instance of a Task that has been started with some input. It can be in various states (e.g., queued, running, awaiting input, succeeded, failed) and follows a specific state transition model.
+
+These core concepts form the foundation of Julep's functionality, allowing for the creation of sophisticated, context-aware applications with powerful agent capabilities.

docs/explanation/default_system_template.md

@@ -0,0 +1,71 @@
+# Default System Template in Julep
+
+Julep uses a default system template for sessions when a custom one is not provided. This template is written in Jinja2 and incorporates various elements from the agent, user, and session context. Here's a breakdown of the template:
+
+```jinja
+{%- if agent.name -%}
+You are {{agent.name}}.{{" "}}
+{%- endif -%}
+
+{%- if agent.about -%}
+About you: {{agent.name}}.{{" "}}
+{%- endif -%}
+
+{%- if user -%}
+You are talking to a user
+  {%- if user.name -%}{{" "}} and their name is {{user.name}}
+    {%- if user.about -%}. About the user: {{user.about}}.{%- else -%}.{%- endif -%}
+  {%- endif -%}
+{%- endif -%}
+
+{{"\n\n"}}
+
+{%- if agent.instructions -%}
+Instructions:{{"\n"}}
+  {%- if agent.instructions is string -%}
+    {{agent.instructions}}{{"\n"}}
+  {%- else -%}
+    {%- for instruction in agent.instructions -%}
+      - {{instruction}}{{"\n"}}
+    {%- endfor -%}
+  {%- endif -%}
+  {{"\n"}}
+{%- endif -%}
+
+{%- if tools -%}
+Tools:{{"\n"}}
+  {%- for tool in tools -%}
+    {%- if tool.type == "function" -%}
+      - {{tool.function.name}}
+      {%- if tool.function.description -%}: {{tool.function.description}}{%- endif -%}{{"\n"}}
+    {%- else -%}
+      - {{ 0/0 }} {# Error: Other tool types aren't supported yet. #}
+    {%- endif -%}
+  {%- endfor -%}
+{{"\n\n"}}
+{%- endif -%}
+
+{%- if docs -%}
+Relevant documents:{{"\n"}}
+  {%- for doc in docs -%}
+    {{doc.title}}{{"\n"}}
+    {%- if doc.content is string -%}
+      {{doc.content}}{{"\n"}}
+    {%- else -%}
+      {%- for snippet in doc.content -%}
+        {{snippet}}{{"\n"}}
+      {%- endfor -%}
+    {%- endif -%}
+    {{"---"}}
+  {%- endfor -%}
+{%- endif -%}
+```
+
+This template dynamically includes:
+1. Agent information (name and description)
+2. User information (if present)
+3. Agent instructions
+4. Available tools
+5. Relevant documents
+
+By using this template, Julep ensures that each session starts with a comprehensive context, allowing the agent to understand its role, the user it's interacting with, and the resources at its disposal.