monadical/internalai-agent
13
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add concise README with setup, quickstart, and AGENTS.md overview

Browse Source
This commit is contained in:
Mathieu Virbel
2026-02-10 18:24:55 -06:00
parent b18ee3b564
commit a17cf63d2f
1 changed files with 20 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
README.md
View File

@@ -4,16 +4,11 @@ A documentation and pattern library that gives LLM agents the context they need
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
## Setup
### 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`:
1. Install [opencode](https://opencode.ai)
2. Make sure InternalAI is running locally (ContactDB + DataIndex accessible via http://localhost:42000)
3. Configure LiteLLM — add to `~/.config/opencode/config.json`:
```json
{
@@ -38,78 +33,33 @@ To use models through LiteLLM, add the following to `~/.config/opencode/config.j
Replace `xxxxx` with your actual LiteLLM API key.
### Running opencode
## Quickstart
From the project root:
1. Run `opencode` from the project root
2. Ask it to create a workflow, e.g.: *"Create a workflow that shows all meetings about Greyhaven in January"*
3. The agent reads `AGENTS.md`, proposes a plan, and generates a notebook like `workflows/001_greyhaven_meetings_january.py`
4. Run it: `uvx marimo edit workflows/001_greyhaven_meetings_january.py`
5. Iterate — review the output in marimo, go back to opencode and ask for refinements
```bash
opencode
```
## How AGENTS.md is Structured
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:
`AGENTS.md` is the entry point that opencode reads automatically. It routes the agent to the right documentation:
| Topic | File |
|-------|------|
| Company context, tools, connectors overview | `docs/company-context.md` |
| Company context, tools, connectors | `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` |
| Notebook templates and patterns | `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`
It also includes API base URLs, a translation table mapping natural-language questions to API calls, and rules for when/how to create workflow notebooks.
## 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