feat: first commit

2026-02-10 18:19:30 -06:00
commit b18ee3b564
8 changed files with 1322 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,120 @@
+# 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
+```