121 lines
4.4 KiB
Markdown
121 lines
4.4 KiB
Markdown
# InternalAI Agent
|
|
|
|
A documentation and pattern library that gives LLM agents the context they need to build data analysis workflows against Monadical's internal systems — ContactDB (people directory) and DataIndex (unified data from email, calendar, Zulip, meetings, documents).
|
|
|
|
The goal is to use [opencode](https://opencode.ai) (or any LLM-powered coding tool) to iteratively create [marimo](https://marimo.io) notebook workflows that query and analyze company data.
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
|
|
- [opencode](https://opencode.ai) installed
|
|
- Access to the InternalAI platform (ContactDB + DataIndex running locally, accessible via http://localhost:42000)
|
|
|
|
### Configuring opencode with LiteLLM
|
|
|
|
To use models through LiteLLM, add the following to `~/.config/opencode/config.json`:
|
|
|
|
```json
|
|
{
|
|
"$schema": "https://opencode.ai/config.json",
|
|
"provider": {
|
|
"litellm": {
|
|
"npm": "@ai-sdk/openai-compatible",
|
|
"name": "Litellm",
|
|
"options": {
|
|
"baseURL": "https://litellm.app.monadical.io",
|
|
"apiKey": "xxxxx"
|
|
},
|
|
"models": {
|
|
"Kimi-K2.5-dev": {
|
|
"name": "Kimi-K2.5-dev"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Replace `xxxxx` with your actual LiteLLM API key.
|
|
|
|
### Running opencode
|
|
|
|
From the project root:
|
|
|
|
```bash
|
|
opencode
|
|
```
|
|
|
|
opencode will pick up `AGENTS.md` automatically and use it as the entry point to understand the project, the available APIs, and how to write workflows.
|
|
|
|
## How AGENTS.md Works
|
|
|
|
`AGENTS.md` is the routing guide for LLM agents. It is structured as follows:
|
|
|
|
1. **Purpose statement** — Explains that the agent's job is to build marimo notebooks that analyze company data.
|
|
|
|
2. **Documentation routing table** — Directs the agent to the right file depending on the topic:
|
|
|
|
| Topic | File |
|
|
|-------|------|
|
|
| Company context, tools, connectors overview | `docs/company-context.md` |
|
|
| People, contacts, relationships | `docs/contactdb-api.md` |
|
|
| Querying emails, meetings, chats, docs | `docs/dataindex-api.md` |
|
|
| Connector-to-entity-type mappings | `docs/connectors-and-sources.md` |
|
|
| Notebook creation patterns and templates | `docs/notebook-patterns.md` |
|
|
|
|
3. **API base URLs** — ContactDB and DataIndex endpoints (both via Caddy proxy and direct).
|
|
|
|
4. **Common query translation table** — Maps natural-language questions (e.g. "Who am I?", "Recent meetings") to the corresponding API calls.
|
|
|
|
5. **Workflow rules** — When to create a notebook vs. answer inline, naming conventions, and the requirement to propose a plan before implementing.
|
|
|
|
## Workflow
|
|
|
|
### How it works
|
|
|
|
1. **Ask a question in opencode** — Describe what you want to analyze (e.g. "Show me all meetings about Greyhaven in January").
|
|
|
|
2. **Agent reads AGENTS.md** — opencode picks up the routing guide and navigates to the relevant docs to understand the APIs.
|
|
|
|
3. **Agent proposes a plan** — Before writing code, the agent outlines: Goal, Data Sources, Algorithm, and Output Format.
|
|
|
|
4. **Agent creates a marimo notebook** — A `.py` file is written to `workflows/` following the naming convention `<NNN>_<topic>_<scope>.py`.
|
|
|
|
5. **Iterate** — Run the notebook with `marimo edit workflows/<name>.py`, review the output, and ask the agent to refine.
|
|
|
|
### Workflow output format
|
|
|
|
Workflows are [marimo notebooks](https://marimo.io) — plain Python files with `@app.cell` decorators. They typically follow this structure:
|
|
|
|
- **params cell** — User-editable parameters (search terms, date ranges, contact names)
|
|
- **config cell** — API base URLs
|
|
- **setup cell** — Shared imports (`httpx`, `polars`, `marimo`)
|
|
- **data cells** — Fetch and transform data from ContactDB / DataIndex
|
|
- **output cells** — Tables, charts, or markdown summaries
|
|
|
|
### Naming convention
|
|
|
|
```
|
|
workflows/<NNN>_<topic>_<scope>.py
|
|
```
|
|
|
|
Examples:
|
|
- `001_greyhaven_meetings_january.py`
|
|
- `002_email_activity_q1.py`
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
internalai-agent/
|
|
├── AGENTS.md # LLM agent routing guide (entry point)
|
|
├── README.md
|
|
├── docs/
|
|
│ ├── company-context.md # Monadical org, tools, key concepts
|
|
│ ├── contactdb-api.md # ContactDB REST API reference
|
|
│ ├── dataindex-api.md # DataIndex REST API reference
|
|
│ ├── connectors-and-sources.md # Connector → entity type mappings
|
|
│ └── notebook-patterns.md # Marimo notebook templates and patterns
|
|
└── workflows/ # Generated analysis notebooks go here
|
|
```
|