76 lines
5.3 KiB
Markdown
76 lines
5.3 KiB
Markdown
# Agent Documentation — InternalAI Platform
|
|
|
|
The InternalAI platform aggregates company data from email, calendars, Zulip chat, meetings, and documents into two core APIs. These docs give LLM agents the context they need to build programmatic workflows — typically as marimo notebooks — that answer analytical questions about people and their interactions.
|
|
|
|
As an agent, assume you're running within our greywall sandbox.
|
|
|
|
## Routing Table
|
|
|
|
| I need to... | Read |
|
|
|---------------------------------------------|---------------------------------------------------|
|
|
| Know who the user is and what they care about | [MYSELF.md] |
|
|
| Understand the company and its tools | [company skill] |
|
|
| Look up people, contacts, relationships | [contactdb skill] |
|
|
| Query emails, meetings, chats, documents | [dataindex skill] |
|
|
| Know which connector provides what data | [connectors skill] |
|
|
| Create a marimo analysis notebook | [workflow skill] + [notebook-patterns skill] |
|
|
| Build a weekly checkout | [checkout skill] |
|
|
|
|
## About the User
|
|
|
|
If `MYSELF.md` exists in the project root, **read it first** before starting any workflow. It contains the user's name, role, team, frequent collaborators, and preferences. Use this context to:
|
|
|
|
- Address the user by name in notebook markdown
|
|
- Default `TARGET_PERSON` or filter values to people they work with
|
|
- Scope date ranges and topics to their stated interests
|
|
- Tailor output format to their preferences
|
|
|
|
If `MYSELF.md` does not exist, ask the user to copy `MYSELF.example.md` to `MYSELF.md` and fill it in, or proceed without personalization.
|
|
|
|
## API Base URLs
|
|
|
|
| Service | Swagger UI | OpenAPI JSON |
|
|
|------------|---------------------------------------------------|----------------------------------------|
|
|
| ContactDB | `http://localhost:42000/contactdb-api/docs` (direct), or `http://caddy/contactdb-api/docs` (via greywall sandbox) | `/contactdb-api/openapi.json` |
|
|
| DataIndex | `http://localhost:42000/dataindex/docs` (direct), or `http://caddy/dataindex/docs` (via greywall sandbox) | `/dataindex/openapi.json` |
|
|
|
|
## Common Questions → API Calls
|
|
|
|
Use this table to translate natural language questions into API calls. The base URLs below assume Caddy proxy (`http://localhost:42000`).
|
|
|
|
| Question | API Call | Notes |
|
|
|----------|----------|-------|
|
|
| "Who am I?" | `GET /contactdb-api/api/contacts/me` | Returns your contact record: name, emails, bio, contact_id |
|
|
| "Find Alice" / "Who is Alice?" | `GET /contactdb-api/api/contacts?search=Alice` | Returns matching contacts with their IDs |
|
|
| "What's Alice's contact ID?" | `GET /contactdb-api/api/contacts?search=Alice` → use `contacts[0].id` | Needed for all DataIndex queries about a person |
|
|
| "Find contact by email" | `GET /contactdb-api/api/contacts/by-email/{email}` | Direct lookup |
|
|
| "My recent meetings" | `GET /dataindex/api/v1/query?entity_types=meeting&contact_ids={my_id}` | Get `my_id` from `/contacts/me` first |
|
|
| "Emails with Alice" | `GET /dataindex/api/v1/query?entity_types=email&contact_ids={alice_id}` | Matches sender, to, or cc |
|
|
| "What was discussed about X?" | `POST /dataindex/api/v1/search` with `{"search_text": "X"}` | Semantic search across all data |
|
|
| "Zulip threads about hiring" | `GET /dataindex/api/v1/query?entity_types=threaded_conversation&search=hiring` | Text filter on content |
|
|
| "My calendar this week" | `GET /dataindex/api/v1/query?entity_types=calendar_event&contact_ids={my_id}&date_from=...&date_to=...` | Set date range |
|
|
| "Who are the most active contacts?" | `GET /contactdb-api/api/contacts?sort_by=hotness&min_hotness=50` | Hotness = 0-100 interaction score |
|
|
| "What connectors are available?" | `GET /dataindex/api/v1/connectors/status` | Lists all data sources and sync status |
|
|
|
|
**Key pattern:** Any question about "me" / "my" / "I" requires calling `GET /contactdb-api/api/contacts/me` first to get your `contact_id`, then using that ID in subsequent DataIndex queries.
|
|
|
|
## File Index
|
|
|
|
- [MYSELF.md] — User identity, role, collaborators, and preferences (gitignored, copy from `MYSELF.example.md`)
|
|
- [company skill] — Business context, team structure, vocabulary
|
|
- [contactdb skill] — ContactDB entities and REST endpoints
|
|
- [dataindex skill] — DataIndex entity types, query modes, REST endpoints
|
|
- [connectors skill] — Connector-to-entity-type mapping
|
|
- [workflow skill] — How to create marimo analysis notebooks
|
|
- [notebook-patterns skill] — Marimo notebook patterns and common API workflows
|
|
- [checkout skill] — Weekly review builder
|
|
|
|
[MYSELF.md]: ./MYSELF.md
|
|
[company skill]: ./.agents/skills/company/SKILL.md
|
|
[contactdb skill]: ./.agents/skills/contactdb/SKILL.md
|
|
[dataindex skill]: ./.agents/skills/dataindex/SKILL.md
|
|
[connectors skill]: ./.agents/skills/connectors/SKILL.md
|
|
[workflow skill]: ./.agents/skills/workflow/SKILL.md
|
|
[notebook-patterns skill]: ./.agents/skills/notebook-patterns/SKILL.md
|
|
[checkout skill]: ./.agents/skills/checkout/SKILL.md
|